Requests and errors

Response shapes

The paths below are relative to /api/v1 on the TKP application URL. Successful REST responses are JSON unless an endpoint streams a file or returns an empty response. There is no common data wrapper:

• /auth/check returns tenant, user, grant_type, interfaces, abilities and libraries directly.
• /libraries returns items, limit, next_cursor and truncated.
• /search/resources returns notice, results, count and strategy.
• A resource-details request returns fields such as id and ingestion_status directly.
• A successful delete can return 204 without a JSON body.

Treat IDs as opaque strings: store the returned values and pass them back unchanged. Do not derive IDs from paths, filenames or titles. A resource can have multiple library-relative paths. For a paginated endpoint, request the next page by sending the returned next_cursor as the cursor query parameter. Keep the same filters and stop when next_cursor is null. Search endpoints instead return up to limit results and do not provide pagination cursors.

Send Accept: application/json. Use Content-Type: application/json for JSON bodies. For uploads, send the file as form field file and let your HTTP client set the Content-Type header. The client then includes the multipart boundary that separates the file from other form fields.

Errors

Errors returned by TKP use application/problem+json with type, title, status, detail and instance. Validation errors can also contain errors keyed by field:

{
  "type": "https://tkp.example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The query field is required.",
  "instance": "/api/v1/search/resources",
  "errors": {"query": ["The query field is required."]}
}

A reverse proxy can return a non-JSON error. Check HTTP status and content type before parsing; do not assume a successful connection means a successful request.

Status	What to check
401	Missing, expired or revoked token; inactive user account; invalid or expired signed URL.
403	Whether the token enables the API interface and has the required permissions; for OAuth, also check the api:use scope.
404	Wrong ID, wrong workspace or library scope. Some access failures deliberately appear as not found.
409	Conflicting library operation. Refresh state before retrying.
413	Instance or proxy upload limit.
422	Request fields and supported upload formats; read errors and detail.
429	Rate limit, full queue or AI budget limit. Check type and detail.
500, 503	Operator logs, service availability and provider configuration.

For a temporary failure during a read, wait before retrying and stop after a fixed deadline or number of attempts. Do not automatically retry an upload or other write after an uncertain network failure: first check whether it succeeded. TKP recognizes byte-identical uploads within a library, but this does not make other write operations safe to repeat.

The quickstart stops on HTTP errors so you can inspect the failure before retrying. Keep credentials and temporary signed URLs out of logs. Share instance and any trace_id with the operator when reporting an error.