ResourceSpace API

Authentication

1. Get the key: each user has a private API key on their account page. An admin can also copy it from Admin → Users → {user} ("Private API Key") S1 S80. On a self-hosted system, $enable_remote_apis = false in config.php turns off remote API access and hides the keys and the test tool; only native mode keeps working S1.
2. Build the query string:
   • user={username}&function={binding}&param1=… (or named parameters);
   • values are percent-encoded;
   • optional parameters can be left out when passed by name;
   • authmode, if present, must be the last parameter S1.
3. Sign: sign = hex(sha256(private_key + query_string)). Send it as sign in the GET query, or POST query, sign and user as form fields S1.
4. Session-key variant: POST login(username, password) to get a session API key. It must be POSTed so the password stays out of URLs and logs. Then sign with it and send authmode=sessionkey S7 S1.
5. Native mode (authmode=native): uses the browser login cookie, through the api() JavaScript helper. Since 10.2 only functions suited to browser use are allowed, and state-changing calls need the CSRF token S1 S11.
6. Integration sign-in (undocumented): development notes mention $api_issue_valid_destinations, a list of allowed callback destinations that lets connectors obtain credentials after a user signs in. It was added for Canva SSO support (developed by SpotDev, 2026-07) and extended for CI-HUB (2026-10-26) S24. Unverified The flow itself is not documented publicly. The Canva and LinkrUI connectors describe "Grant access" / SSO sign-in from the user's side S77 S78.

Core resources

All calls go to GET|POST https://{host}/api/?function={name}…. The table below groups the functions listed in the API reference (93 entries including IIIF and plugin functions, 2026-10-29) S1. Trunk defines 76 core bindings in include/api_bindings.php (11.0 release: 75) S15.

Data model

• A resource has an integer ref and a resource type. Search results return core columns (ref, resource_type, archive, access, file_extension, creation_date, file_checksum, hit_count…) and indexed field values as field{N} keys. The exact payload depends on configuration S2.
• Metadata fields ("resource type fields") have integer IDs and shorthand names. Since 10.2 a field can apply to several resource types S1 S21.
• Fixed-list options (check boxes, drop-downs, category trees, dynamic tags) are nodes with their own IDs. Since 10.0, free text is stored and searched through the node model as well S1 S21.
• Files: one original per resource plus alternative files. Previews come in size codes (e.g. thm, pre, scr, col) under a scrambled filestore path S3 S6 S20.
• Workflow / visibility:
  • archive holds the workflow state: 0 active, 1 pending archive, 2 archived, 3 deleted, -1 pending review, -2 pending submission, plus custom states from the Advanced workflow plugin S2 S68;
  • access sets visibility: open, restricted or confidential S100.
• The full database schema (tables resource, resource_node, node, collection, api_log…) is documented publicly S10.

Search & querying

• do_search(search, restypes, order_by, archive, fetchrows, sort, offset) S2:
  • search uses the standard ResourceSpace syntax: keywords, special search terms, field:value matching, date ranges such as datefield:rangestart2019-01-01end2019-01-07, and partial dates 2019|01|nn;
  • order_by takes relevance, popularity, rating, date, colour, title, resourceid, random, status and others;
  • archive filters by workflow state.
• Paging: fetchrows="offset,limit" returns total plus data. Without it, all matching rows come back (fetchrows=-1) S2 S3. Unverified The two search references disagree on when this arrived: 10.3 for do_search, 10.2 for search_get_previews S2 S3.
• Facets / aggregations: none documented in the API (Unknown). Faceted refining exists in the UI (Refine results plugin) S99.
• Smart search: CLIP natural-language and visual search is a UI plugin; no dedicated API binding is documented (Unknown) S56.
• Basic-search limit: since 10.1, basic search reads only the first 500 characters of long text fields S21.

Uploads & binaries

• Two-step pattern: create_resource (optionally with a file URL and metadata), then attach the file with one of S1 S4 S5:
  • upload_multipart: HTTP multipart/form-data; the file part is not part of the signature;
  • upload_file_by_url: the server fetches a remote URL, which must be allowed by $api_upload_urls;
  • upload_file.
• upload_multipart responses S4:
  • HTTP 204 on success;
  • 413 when the file is too large (server upload limit);
  • 400 for a duplicate, when checksums are enabled;
  • 500 for other errors, with a body {status: "fail", data: {message}}.
  • Since 10.6 it can also replace alternative files and previews S21.
• Chunked / resumable: the web UI chunks large uploads ("no restriction on maximum file size") S30. A chunked API flow is not documented (Unknown). The 11.0 code includes a tus-php configuration (include/tusconfig.php, tied to the user session), which suggests the browser uploader uses the tus resumable protocol S15. Unverified This is inferred from the code; no tus endpoint is documented for API clients.
• Downloads: get_resource_path(ref, size, generate, extension, page, watermarked, alternative, write_metadata) returns a temporary download URL (24 h by default), or an array of URLs when given several IDs S6.
• Bulk / server-side ingestion: StaticSync hot folders and SFTP drop folders (hosted) S64 S27.

Events & webhooks

• No event subscription API. The API Webhooks plugin (10.1) is configured in config.php ($api_webhooks_urls). It shows custom buttons on the resource edit page. When a user clicks one, the server saves the form, then POSTs the resource ID to the configured URL. An optional hash secret adds a SHA-256 hash of the ID so the receiver can check the request S12 S21.
• Only the edit location is supported. Retries and payload schema: Not public S12.
• Polling: resource_log_last_rows returns recent resource log rows, so a remote system can poll for changes S1 S22.
• Notifications: watched searches and email notifications (UI) S95.

Limits & quirks

• Errors can return HTTP 200: Montala notes that failed calls may still return status 200; check the payload S10.
• Signing order matters: the signature covers the exact query string. sign, authmode and pretty are stripped before verification, and authmode must come last S1 S15. Booleans may need to be sent as 1/0 S4.
• Disabled API: $enable_remote_apis=false returns HTTP 403 for non-native calls S15 S1.
• API log (11.1): external userkey requests are logged in api_log; retention 14 days by default, minimum 7; specific usernames can be excluded S1 S24.
• No rate limiting today: throttling is still a roadmap item, so self-hosters need their own web-server limits S23.
• Behaviour depends on configuration: returned fields, previews and permissions all follow the signing user and the instance's plugins and configuration S2 S8.
• Reference error: on the API index, the update_resource_lock entry links to the validate_upload_url page S1.
• Typesense search (11.0, experimental) does not apply permissions. Montala advises using it only where every user may see every resource S63.

SDKs, tools & code samples

Changelog of the API