EntryScape API¶

The EntryScape API is a REST API on top of EntryStore for reading and writing catalogs, datasets, distributions and the other DCAT-AP entities, uploading files, importing terminologies and searching. This page gets you from nothing to your first successful calls. The complete reference, with every operation, parameter, response and a code sample in each language, is at entryscape.org/api.

Which host to use

The API runs on its own host, which MetaSolutions provides for your installation. The examples write it as $API. Every request can also name the EntryStore instance it should talk to; leave that out and you get the installation's default.

1. Read without logging in¶

Public data needs no account. Start with the catalogs and follow the ids:

API=https://<your EntryScape API host>

curl -sS "$API/catalog?limit=5"
curl -sS "$API/catalog/1/100/datasets?limit=5"
curl -sS "$API/dataset/1/200"
curl -sS "$API/dataset/1/200/metadata"

Every entity is addressed as {context_id}/{entry_id}, the same two numbers that appear in EntryScape's own URLs. The plain entity URL returns a summary, /metadata returns the full RDF as JSON-LD (add ?format=turtle or another format if you prefer).

Lists and search are served from a search index that is updated a moment after each write, so a brand-new entry can be missing from a list while reading it by id already works.

Reference: List catalogs, Datasets in a catalog, Get dataset, Get dataset metadata.

2. Search¶

curl -sS "$API/search?query=trafik&limit=10"

query is free text; the response lists matching entries with their type and ids, which you then read as above. Facets and filters are described in the reference.

Reference: Search.

3. Log in¶

Writing, and reading anything that is not public, needs an EntryScape account. Log in once and send the token as a header on every later request:

TOKEN=$(curl -sS -X POST "$API/auth/login" \
  -H 'Content-Type: application/json' \
  --data '{"username": "you@example.org", "password": "***"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["auth_token"])')

curl -sS "$API/auth/whoami" -H "X-Auth-Token: $TOKEN"

whoami answers with your user name and "authenticated": true. A guest answer means the token is missing, expired, or belongs to a different EntryStore instance than the one the API is configured for. Scripts need nothing more than the X-Auth-Token header; the login endpoint is rate limited, so do not retry a wrong password in a loop.

Reference: Log in, Who am I.

4. Create and update¶

A create takes the entity's metadata as JSON-LD and the context (catalog) to create it in. The response gives you the new ids:

curl -sS -X POST "$API/dataset?context=1" \
  -H "X-Auth-Token: $TOKEN" \
  -H 'Content-Type: application/ld+json' \
  --data-binary @- <<'JSON'
{
  "@type": "http://www.w3.org/ns/dcat#Dataset",
  "http://purl.org/dc/terms/title": [{"@value": "Air quality 2026", "@language": "en"}],
  "http://purl.org/dc/terms/description": [{"@value": "Hourly measurements", "@language": "en"}]
}
JSON

To change an entity, PUT the complete metadata to its /metadata URL; the graph you send replaces what was there. Metadata is validated against the installation's DCAT-AP profile before it is written: violations come back as 422 with a report saying which property failed, and warnings are returned alongside a successful 201. You can also run that validation on a stored entity at any time with its /validate URL.

Reference: Create dataset, Update dataset metadata, Validate dataset, Delete dataset. The other entities (catalog, distribution, data service, contact, organization, document, idea, showcase, suggestion) follow the same pattern.

5. Upload a file to a distribution¶

Files are handled by background jobs. Pass the resource URI of the distribution to add a new file, or of the file to replace one (both are shown under the distribution's information icon in EntryScape Catalog, see detailed information):

curl -sS -X POST "$API/distribution/addFile?resourceURI=https://<store>/store/1/resource/300" \
  -H "X-Auth-Token: $TOKEN" \
  -F 'file=@data.csv'

The reply is 202 with a jobId. Poll the job until it reaches SUCCESS or FAILED:

curl -sS "$API/job/1787937550074240" -H "X-Auth-Token: $TOKEN"

For an add, the finished job's resultUrl is the new file's resource URI, which is what a later replace takes. If the distribution has an auto-generated API, the job also updates that API, and only CSV files are accepted for it.

Reference: Add file, Replace file, Job status. Moving from the old Taskrunner API? See Migrating from Taskrunner.

6. Use an SDK or the MCP server¶

You do not have to write HTTP by hand. Generated SDKs for Python, JavaScript, TypeScript and C# wrap every operation, and an MCP server exposes them as tools for AI assistants. Each comes with runnable examples. The MCP server package is also a Claude Code plugin, so one install gives the tools together with a set of skills for the common multi-step tasks. The downloads and the installation notes are on the reference page, and every operation there shows the SDK call next to the curl command.

7. When something fails¶

Errors are JSON with error, message and code. The ones you will meet first:

Code	Meaning
`403`	No or expired token on a write, or no right to the context
`404`	The ids do not name an entity of that type
`413`	Upload larger than the installation's limit (50 MB by default)
`422`	Metadata failed the DCAT-AP validation, or an upload targeted the wrong kind of entry; the body says which
`429`	Too many requests; the `Retry-After` header says when to try again

The reference documents each operation's responses in full.