Skip to main content
The Configuration API lets you manage tenant configuration from your own code. It works on the same configuration as Studio, so changes made through the API show up in Studio and the other way around.

Sources

List, create, update, and delete sources under /v1/sources, and manage each source’s properties.

Applications

Create applications and control their scopes and resource access under /v1/applications.

Managed tags

Maintain managed tags and their values under /v1/managed-tags.

​
Authentication

Every request needs a tenant-scoped credential. The tenant comes from the credential; you cannot select it in the request. Send one of:
  • Authorization: Bearer <token> with an Application access token requested for your tenant ID as the audience.
  • x-api-key: <organization-api-key> with an Occtoo organization API key.
Each operation requires one scope: An Application restricted to specific sources only sees those sources. GET /v1/sources filters out every source the Application cannot access.

​
Pagination

List endpoints use forward-only keyset pagination:
  • limit sets the page size. The default is 50 and the maximum is 200.
  • after continues from the previous page. Pass the after value from the last response; null means you have reached the end.
  • includeTotalCount=true adds totalCount to the response. Otherwise it is null.
Keep the same filters when you follow an after cursor.

​
Updates and concurrency

  • PATCH /v1/sources/{sourceId} changes only the fields you send. Omitted or null fields keep their current value; send an empty description to clear it.
  • PUT /v1/sources/{sourceId}/properties/{propertyId} creates the property or updates it. null optional fields keep their current value.
  • PUT on applications, managed tags, and managed tag values replaces the resource. Omitted collections become empty.
  • Application updates require the etag from your latest read. If the Application changed since then, the update returns 409. Read it again and retry.

​
Application access

Call GET /v1/applications/access-catalog to discover what an Application can be granted. The catalog is a tree of access nodes. Use the key of Scope nodes in scopeKeys, Resource nodes in resourceSelectors, and Api nodes in apiSelectors when you create or update an Application. POST /v1/applications returns the client secret once. Store it securely; later reads never return it. Deleting an Application revokes its credentials.

​
Asynchronous changes

Some changes finish in the background after the API responds:
  • Deleting a source soft-deletes it and starts cleanup. The API does not offer hard deletion.
  • Deleting a source property starts the property cleanup.
  • Changing a property’s type can trigger reindexing. Read the property again to follow its state from Updating back to Active.

​
Errors

Errors use Problem Details (application/problem+json). Validation failures list the invalid fields under errors. Deleting a managed tag or managed tag value that is already gone returns 204.