Compile a selected operation from an approved API document for review

POST

/katara/v1/orgs/{org_id}/environments/{environment_id}/tools/openapi/compile

const url = 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/tools/openapi/compile';
const options = {
  method: 'POST',
  headers: {
    'X-Katara-CSRF': '1',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"source":{"org_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","environment_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","version":1,"integrity":"example","media_type":"application/json","size_bytes":1},"selection":{"operation_id":"example","server_url":"https://example.com","server_variables":{"additionalProperty":"example"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/tools/openapi/compile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "source": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "application/json", "size_bytes": 1 }, "selection": { "operation_id": "example", "server_url": "https://example.com", "server_variables": { "additionalProperty": "example" } } }'

Requires locus:tools:write and current read access to the approved source. Source integrity, tenant, environment and reset are checked before parsing and again before response delivery. JSON or YAML (stored as text/plain), up to 1 MiB, is parsed in a no-network worker. Select an operation ID, exact declared HTTPS server and explicit server variables. Supports the bounded OpenAPI 3.0/3.1 JSON HTTP profile; unsupported features fail explicitly. External references, callbacks, multipart/binary bodies, cookies and caller-supplied credential headers are refused. Responses contain exact operation_json bytes and their SHA-256, preserving numeric schema bounds across clients. This creates no tool, credential, approval or external effect. No automatic retry.

Authorizations

Parameters

Path Parameters

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

X-Katara-CSRF

Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Body^required

application/json

object

source

required

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9007199254740991

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: application/json text/plain

size_bytes

required

integer

>= 1 <= 1048576

selection

required

object

operation_id

required

string

/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/

server_url

required

string format: uri

<= 2048 characters /^https://[^\s\\%@?#{}]+$/

server_variables

required

object

<= 32 properties

key

additional properties

string

>= 1 characters <= 256 characters

Responses

200

Successful request

application/json

object

source

required

object

org_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

environment_id

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

required

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

version

required

integer

>= 1 <= 9007199254740991

integrity

required

string

/^sha256:[a-f0-9]{64}$/

media_type

required

Allowed values: application/json text/plain

size_bytes

required

integer

>= 1 <= 1048576

selection

required

object

operation_id

required

string

/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/

server_url

required

string format: uri

<= 2048 characters /^https://[^\s\\%@?#{}]+$/

server_variables

required

object

<= 32 properties

key

additional properties

string

>= 1 characters <= 256 characters

reset_epoch

required

integer

>= 1 <= 9007199254740991

profile

required

Allowed value: openapi-json-http/v1

operation_json

required

string

>= 2 characters <= 2097152 characters

operation_digest

required

string

/^sha256:[a-f0-9]{64}$/

Example

{
  "source": {
    "media_type": "application/json"
  },
  "profile": "openapi-json-http/v1"
}

409

Account_changed: reload and review with the signed-in account.

422

Unsupported API feature, invalid document or resource limit.

default

Request error

application/json

object

error

required

object

message

required

string

>= 1 characters <= 500 characters

type

required

string

>= 1 characters <= 100 characters

code

required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string

>= 1 characters <= 100 characters

param

required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null

request_id

required

string

>= 1 characters <= 100 characters

upstream_status

required

integer | null

action

Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support

operation_id

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

snapshot_ref

string format: uuid

/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Allowed value: 00000000-0000-0000-0000-000000000000

Example

{
  "error": {
    "action": "sign_in"
  }
}

Compile a selected operation from an approved API document for review

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

409

422

default

Example

Request Body^required