REST api documentation?


I’m experimenting with omeka-s and I’m wondering what is the status of REST api? Should it be usable?

With omeka classic I could use api/items?key=KEY for authentication but if I try that with Omeka-s I get Temporary Redirect 307.
Is the login schema changed?

BTW. I made a Docker setup for quickly testing omeka-s:


api/items should work fine, and give something like this. (We’re still sorting out where the developer documentation will live).


Thanks for reply and sorry for hastily made question!

I figured out that I had a stupid extra / in my POST just before “?key”.

However, I’m still not able to create items. I tried something like this:
curl -XPOST -H “Content-type: application/json” -d '{
"@context": {
“o”: “”,
“foaf”: {
"@id": “”,
“vocabulary_id”: 4,
“vocabulary_label”: “Friend of a Friend”
“dcterms”: {
"@id": “”,
“vocabulary_id”: 1,
“vocabulary_label”: “Dublin Core”

“dcterms:description”: [
"@value": “Joan of Arc has become a world famoY”,
“value_id”: 4,
“property_id”: 4,
“property_label”: “Description”
}’ ‘http://localhost:8000/api/items?key=CtxuMrszP4LQSAyoTJWnk7KU11qq67WW

It always says that “Permission denied for the current user to create the Omeka\Api\Adapter\ItemAdapter resource.” even if I have the key created.

Any change to have a working example of posting an item?


For authentication the Omeka S API uses a two-part key: the “key_identity” and “key_credential”. When you created your key you should have seen a message that included both. If you didn’t make note of your key_credential you’ll need to create another key because it’s otherwise irretrievable. So your URL will look something like this:



Thank you Jim, now things are working like expected!

I noticed that creating items requires “type” field. If that is not set, the result is an empty item.

In case someone else wants to try here is a working example:

curl -XPOST -H "Content-type: application/json" -d '{
    "dcterms:title": [
            "type": "literal",
            "property_id": 1,
            "property_label": "Title",
            "@value": "Dear API, please save me!"
    "dcterms:description": [
            "type": "literal",
            "property_id": 4,
            "property_label": "Description",
            "@value": "Thank you"
}' 'http://localhost:8000/api/items?key_identity=YOUR_KEY&key_credential=YOUR_CREDENTIAL'

Example API usage (using curl)

Could you kindly provide an example of uploading a file via REST?

I think this is the JSON part for attaching media to item (id=15), right?

    "o:item": {
        "@id": "http:\/\/localhost:8000\/api\/items\/6",
        "o:id": 15

And the url I figured out is this: http://localhost:8000/api/media

But how do I actually upload the file? I’ve tried with form-data but the response is that “The API request content must be a JSON object (for HTTP) or PHP array”