Orange Logic (Cortex) API

Authentication

Prerequisite (all token types) S4

1. An admin opens Administration → Contacts → Accounts, picks the account type (usually OAuth Client Application Accounts) and the user.
2. Sets SSO Status = "Non SSO Authentication allowed" and ticks Allow Bearer Authentication. This cannot be done on an existing SSO user; create a dedicated API account (or ask support) S4.
3. Give the account the Security Functions it needs (e.g. Can bypass new device login verification, Access to the search API) and asset Permissions; the docs recommend one API account per use case, re-created in production after testing S3.

Sending credentials: Authorization: Bearer {token} (OAuth / bearer) S7 S9; legacy /api/ calls also accept a Token parameter/header (empty → cookie) S10 S58. Failure reasons are returned as coded messages (e.g. 401 Invalid Access Token, 403 Unrecognized Computer, 403 Account Only Permit SSO) since the London release S6.

Discovery (observed on the vendor's own instance) S64 S65: /.well-known/openid-configuration lists authorization_code and client_credentials, userinfo_endpoint = /webapi/security/oauth2/userinfo_490_v1, RS256 ID tokens and a JWKS at /.well-known/jwks.json; /.well-known/oauth-authorization-server (used by MCP clients) lists authorization_code + refresh_token, PKCE S256, token_endpoint_auth_methods: client_secret_post, none, a dynamic client registration endpoint (/webapi/extensibility/integrations/mcp/register_42YV_v1) and a revocation endpoint. Unverified Whether every customer instance exposes identical metadata is Unknown.

Impersonation: the Search API accepts impersonateanotheruser (email) and returns what that user would see, capped by the caller's own rights S33; admins can impersonate users to test Content Browser access S1.

Core resources

Paths are relative to https://{tenant}. "Spec" = an embedded OpenAPI definition exists (archived on DAM Wiki: API spec downloads); "Prose" = documented in text only.

Data model

• Objects: everything is a database object — Documents (files and containers: folders "Story", virtual folders "Album", projects, products…), Contacts (users of several account types, groups) and Keywords (tags grouped by Tag Type) S34 S41. Each asset has a type (Image, Video, Audio, Multimedia/Other…) and a configurable subtype that carries its own metadata layout; the MCP page notes subtypes are now called "objects" in the UI S13 S16.
• Identifiers S16 S17: Unique identifier / SystemIdentifier (e.g. CTL898546, shown in UI), Media Encrypted Identifier = RecordID (e.g. 2RBKT7U02J5F, not shown in UI, protected by security level), asset key (random string in embed links), plus a Legacy identifier (CoreField.Id_Client) for external IDs. DataTable uses prefixed record IDs (DO_, CT_, CG_, AS_) S63.
• Metadata fields: addressed by API name Namespace.FieldName (built-ins use CoreField, e.g. CoreField.Title, CoreField.CaptionLong, CoreField.Purpose = Visibility Class), system name, or SystemID (custom fields only) S17. Field kinds include multi-value, authority lists, linked fields, paired-value fields (ValueLeft/ValueRight), inherited and related (read-only), computed dates, advanced interval dates (2025-09-20/NA) S36 S42.
• Files & renditions: originals plus proxies / asset formats identified by codes configured per tenant (typical: TR1 1200 px, TR4, TR7 thumbnails; on-demand TRX, CMS1–3; video WebHigh) S16 S35. Stacks group alternates under a lead asset S32. Versions are uploaded with UploadNewVersion S38.
• Visibility Classes (formerly "purposes") and optional security clearance levels (settable at upload via clearanceLevel) add access layers on top of Permissions S34 S39.

Search & querying

• query syntax criterion:term; operators AND (default, space), OR, NOT; precedence NOT > AND > OR; parentheses; date operators :, >, >:, <, <: with YYYY[-MM[-DD]] or YYYY-MM-DDTHH.MM.SS S34.
• Standard criteria include DocType, DocSubType, Path (wildcard allowed, costly), ParentFolderIdentifier (whole folder tree, not virtual folders), Purpose, Text (free text / exact phrase), Keyword(TagType), NativeKeyword, RecordID, SystemIdentifier, MediaDate, CreateDate, EditDate, Participant("Role"), Fileextension, Title; any field flagged "Searchable individually" is queryable as Namespace.Field S34. List them per tenant with ListCriteria S58.
• Index is Elasticsearch-based (tokenised; use wildcards for substring matches) S34. New fields must be indexed before they are searchable S34.
• AI search: semanticquery (Ottawa release+) combines with query S33 S57.
• Options: sort (relevancy and others), fields (comma list, wildcard */namespace.*, Path_{FORMAT} for rendition URLs; 2,048-char limit per value), generateformatifnotexists, getpermanentassetspaths, includebinned (soft-deleted), includestorageinfo, includeassetswithvirtualpaths (Milan+), verbose, format (XML default / JSON), dateformat (.NET specifiers; server locale en-US) S33 S35 S37.
• Hidden stack alternates, TotalCount and NextPage require the Search API - Allow search on all documents Security Function S32 S33.
• Facets/aggregations via API: Not public (not documented). Max countperpage: Not public.
• The original file cannot be fetched through the Search API; an "Extract Original Document" API exists on request via support S35.

Uploads & binaries

• Processing modes (UploadMode / importMode): ProcessInLine, ProcessProxiesInBackground, ProcessProxiesAndParentAndIndexInBackground, ProcessFullyInBackground, ProcessFullyInBackgroundLite S38.
• Embedded metadata is mapped by the folder's import mapping template (sidecar files and central metadata files supported) S38.
• Downloads/delivery: public embed/download links on the CDN (optionally expiring, tracked, transformed), presigned storage URLs (10 min default), Share links, and the permanent/expiring Path_{FORMAT} URLs returned by Search S20 S25 S33. Images can be requested as .auto (AVIF → WebP → JPEG) S20.
• URL transformations appended as /t/{spec},{spec}/: crop (c_…, gravity, AI auto-crop modes Optical, SmartSwatch, GoogleAI, AzureAI), resize (re_…), rotate, metadata keep (fl_Keep), quality, brightness/opacity and image overlays (Queenstown+, overlays in beta) S24.
• IIIF image URLs are supported for unregistered viewers (must be enabled; prerequisite of the Content Browser) S2 S53.

Events & webhooks

• Configured via API (and by Orange Logic for custom automations); requires the Webhook subscription Security Function S46.
• Subscription object: id, name, description, isActive, definition.targetURL, customHeaders, inclusive/exclusive predicates with conditions S47.
• Payload (HTTP POST): EventId (dedupe key), Topic (domain.eventname), EventDateUtc, Data (e.g. {"RecordID": …} — IDs only, fetch details separately), Tenant (instance code), UserId S46.
• Default topics: document.created, document.modified (per save), document.deleted, document.updated (per field; off by default), document.storage_mode_changed; custom topics via the workflow designer's Emit Webhook action S46.
• Delivery: internal queue, up to 5 retries (configurable) S46; since Ottawa, subscriptions failing for more than 7 days are auto-deactivated with e-mail alerts S47.
• Signature: opt-in in Administration → Reference Tables → Configure Modules → Webhooks; HMAC SHA-256 (or SHA-512), Base64, header x-ol-signature; secret set/rotated with rotatesecret_22P_v1 (zero-downtime rotation window configurable) — Kobe release+ S48.
• Loop prevention: send X-Mute-WebHook-Subscriptions / X-Mute-WebHook-Topics (comma list, * wildcard, 512 chars) or equivalent parameters on API calls (Juneau+) S49.
• Async batch-upsert jobs can report completion via webhooks S29.

Limits & quirks

• No published rate limits (Not public); heavy jobs should use background processing, low indexing priority (IndexInBackground=1, IndexingPriority=Medium|Low|VeryLow) or the backup site after contacting support S3 S44.
• Tokens are IP-bound and server-bound: a site failover invalidates them S4 S8.
• GET vs POST: long GET URLs can fail with 403; switch to POST form data. If a parameter is sent both in header and URL, the header wins S2.
• Parameters are mostly case-insensitive, except the OAuth authorize call (lower case required) S15 S11.
• DataTable safety rails: Read/Update/Delete on Documents.All only work when exactly one record matches; multi-record updates need MaxRecordsAffected (max 100) or ApplyAll; TestMode=1 dry-runs; FieldLengthSafety=1 truncates overlong values; blank fields hidden unless Verbose=1; sub-calls in [...] must be percent-encoded S19 S42 S44. DataTable failures come back as coded results (RECORD_NOT_FOUND, UPDATE_FAILED, CREATION_FAILED, MORE_RECORDS_WOULD_BE_AFFECTED_THAN_ALLOWED) in the response body S44 S45; the HTTP status returned with them is not stated (Unknown).
• Response envelope for /api/ and DataTable calls: APIRequestInfo (provider version, login status, session, timeout) + APIResponse/Response; /webapi/ calls return plain JSON S14 S33 S43.
• Instance headers x-cortex-location, x-cortex-providerid, x-cortex-provideridentity, x-cortex-providerversion (e.g. ROME.R17… on the vendor instance in 2026-09) S14 S67.
• Date quirks: Web APIs and DataTable return ISO 8601; Search returns US-formatted dates unless dateformat is set S37.
• Batch upsert: do not update the same record twice in one batch (parallel execution, order not guaranteed) S29.
• CDN: default TTL 24 h; deleted assets stay cached until TTL unless invalidated; CORS Access-Control-Allow-Origin: * S21. HLS is not available for public embed links S20.
• Unverified Some reference pages still link to an older orangedam.readme.io host S12 S48.

SDKs, tools & code samples

No official Python, .NET, Java or PHP REST client was found S72.

Changelog of the API

Release letters map to quarterly releases (Concord = 2022-12 S94; Ottawa announced 2025-11-18 S90); exact dates of the other city releases are Behind login (release notes on the Link help center).