OpenVibe.AI API

Generated at from openvibe-contracts v0.114.0 and openvibe-sdk v0.35.1.

Server https://ai.openvibe.services. 43 routes performing 8 capabilities. OpenAPI 3.1 document.

GET /api/v1/attribution-quotas/{attribution}

Cap what runs attributed to one of the caller's own entities may cost or request per hour or day (a streamer's daily AI budget on Live).

Capabilities
ai.quota.attribution.manage
Visibility
first-party
Parameters
  • attribution (path, required)
Input
ai.attribution-quota-put@1
Response
application/json ai.attribution-quota@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.quota.attribution.manage</strong> (first-party): Cap what runs attributed to one of the caller&#39;s own entities may cost or request per hour or day (a streamer&#39;s daily AI budget on Live). Only the service named in the attribution sets, reads or removes its caps; a run over a cap is refused before any provider is called.</p>

PUT /api/v1/attribution-quotas/{attribution}

Cap what runs attributed to one of the caller's own entities may cost or request per hour or day (a streamer's daily AI budget on Live).

Capabilities
ai.quota.attribution.manage
Visibility
first-party
Parameters
  • attribution (path, required)
Request body
application/json ai.attribution-quota-put@1
Response
application/json ai.attribution-quota@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.quota.attribution.manage</strong> (first-party): Cap what runs attributed to one of the caller&#39;s own entities may cost or request per hour or day (a streamer&#39;s daily AI budget on Live). Only the service named in the attribution sets, reads or removes its caps; a run over a cap is refused before any provider is called.</p>

DELETE /api/v1/attribution-quotas/{attribution}

Cap what runs attributed to one of the caller's own entities may cost or request per hour or day (a streamer's daily AI budget on Live).

Capabilities
ai.quota.attribution.manage
Visibility
first-party
Parameters
  • attribution (path, required)
Input
ai.attribution-quota-put@1
Response
application/json ai.attribution-quota@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.quota.attribution.manage</strong> (first-party): Cap what runs attributed to one of the caller&#39;s own entities may cost or request per hour or day (a streamer&#39;s daily AI budget on Live). Only the service named in the attribution sets, reads or removes its caps; a run over a cap is refused before any provider is called.</p>

GET /api/v1/audit

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

GET /api/v1/cache

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

DELETE /api/v1/cache

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Input
ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

POST /api/v1/chat

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/classify

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

GET /api/v1/credentials/{subject}

Store, read (never the key) or delete a person's own provider key, for runs made on their behalf with it (ai.run-request credential).

Capabilities
ai.credential.manage
Visibility
first-party
Parameters
  • subject (path, required)
  • provider (query, required) — openai = any OpenAI-compatible endpoint.
  • base_url (query)
  • api_key (query) — Required the first time, and whenever provider or base_url changes (a key is never sent to a new endpoint without being entered again); otherwise the stored key is kept.
  • models (query) — Model per Live role; `chat` is the default for the others.
  • budget_usd_per_day (query) — The person's own daily cap on estimated spend with this key; 0 or absent = no cap.
Input
ai.credential-put@1
Response
application/json ai.credential@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.credential.manage</strong> (first-party): Store, read (never the key) or delete a person&#39;s own provider key, for runs made on their behalf with it (ai.run-request credential). Only the service that stored a credential reads, uses or changes it.</p>

PUT /api/v1/credentials/{subject}

Store, read (never the key) or delete a person's own provider key, for runs made on their behalf with it (ai.run-request credential).

Capabilities
ai.credential.manage
Visibility
first-party
Parameters
  • subject (path, required)
Request body
application/json ai.credential-put@1
Response
application/json ai.credential@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.credential.manage</strong> (first-party): Store, read (never the key) or delete a person&#39;s own provider key, for runs made on their behalf with it (ai.run-request credential). Only the service that stored a credential reads, uses or changes it.</p>

DELETE /api/v1/credentials/{subject}

Store, read (never the key) or delete a person's own provider key, for runs made on their behalf with it (ai.run-request credential).

Capabilities
ai.credential.manage
Visibility
first-party
Parameters
  • subject (path, required)
  • provider (query, required) — openai = any OpenAI-compatible endpoint.
  • base_url (query)
  • api_key (query) — Required the first time, and whenever provider or base_url changes (a key is never sent to a new endpoint without being entered again); otherwise the stored key is kept.
  • models (query) — Model per Live role; `chat` is the default for the others.
  • budget_usd_per_day (query) — The person's own daily cap on estimated spend with this key; 0 or absent = no cap.
Input
ai.credential-put@1
Response
application/json ai.credential@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.credential.manage</strong> (first-party): Store, read (never the key) or delete a person&#39;s own provider key, for runs made on their behalf with it (ai.run-request credential). Only the service that stored a credential reads, uses or changes it.</p>

POST /api/v1/embed

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/enrich

Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller's own runs and attach citations to them.

Capabilities
ai.run.create
Visibility
first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/extract

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/generate

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

GET /api/v1/models

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/models

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

PATCH /api/v1/models/{provider}/{model}

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Parameters
  • provider (path, required)
  • model (path, required)
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

GET /api/v1/providers

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/providers

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

PATCH /api/v1/providers/{key}

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

POST /api/v1/providers/{key}/disable

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

POST /api/v1/providers/{key}/enable

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

POST /api/v1/providers/{key}/reset

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

GET /api/v1/quotas

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/quotas

Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.

Capabilities
ai.provider.manage
Visibility
internal
Request body
application/json ai.provider-manage-request@1
Response
application/json ai.provider-manage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.provider.manage</strong> (internal): Register, update, enable and disable providers and models (secrets only as env references, never values), reset circuit breakers, set quotas and purge the cache.</p>

GET /api/v1/requests

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/routes/{key}/versions

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>

POST /api/v1/routes/{key}/versions/{version}/status

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
  • version (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>

GET /api/v1/runs

Read the caller's own runs, their citations and request-log metadata (hashes, tokens, latency; never raw prompts).

Capabilities
ai.run.read
Visibility
first-party
Response
application/json ai.run-read-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.read</strong> (first-party): Read the caller&#39;s own runs, their citations and request-log metadata (hashes, tokens, latency; never raw prompts).</p>

POST /api/v1/runs

Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller's own runs and attach citations to them.

Capabilities
ai.run.create
Visibility
first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

GET /api/v1/runs/{id}

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.read
Visibility
public, first-party
Parameters
  • id (path, required)
Input
ai.run-create-request@1
Response
application/json one of ai.run-create-result@1, ai.run-read-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.read</strong> (first-party): Read the caller&#39;s own runs, their citations and request-log metadata (hashes, tokens, latency; never raw prompts).</p>

POST /api/v1/runs/{id}/cancel

Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller's own runs and attach citations to them.

Capabilities
ai.run.create
Visibility
first-party
Parameters
  • id (path, required)
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

GET /api/v1/runs/{id}/citations

Read the caller's own runs, their citations and request-log metadata (hashes, tokens, latency; never raw prompts).

Capabilities
ai.run.read
Visibility
first-party
Parameters
  • id (path, required)
Response
application/json ai.run-read-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.read</strong> (first-party): Read the caller&#39;s own runs, their citations and request-log metadata (hashes, tokens, latency; never raw prompts).</p>

POST /api/v1/runs/{id}/citations

Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller's own runs and attach citations to them.

Capabilities
ai.run.create
Visibility
first-party
Parameters
  • id (path, required)
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/runs/{id}/retry

Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller's own runs and attach citations to them.

Capabilities
ai.run.create
Visibility
first-party
Parameters
  • id (path, required)
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

GET /api/v1/status

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/summarize

Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app's own runs.

Capabilities
ai.app.run, ai.run.create
Visibility
public, first-party
Request body
application/json ai.run-create-request@1
Response
application/json ai.run-create-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.app.run</strong> (public): Run the AI operations as a developer app (ADR-014): POST /api/v1/chat, /generate, /summarize, /classify, /extract, /embed and GET /api/v1/runs/:id for the app&#39;s own runs. The app token (sub app:app_&lt;ULID&gt;, project_id prj_&lt;ULID&gt;, env sandbox|production, audience openvibe.ai) runs as its project: every run is metered (platform.usage-sample@1 to OpenVibe.Billing, subject project:prj_&lt;ULID&gt;) against the project&#39;s bounded free allowance, and metered capacity is spent only under the project&#39;s tier budget; a sandbox run, and every run no tier budget governs, uses only free and local capacity. An app runs only these operations (never a workflow by key), never reads another project&#39;s runs, and never uses a person&#39;s BYO provider key.</p> <p><strong>ai.run.create</strong> (first-party): Create workflow runs (POST /api/v1/runs and the direct chat/generate/summarize/classify/extract/enrich/embed operations), cancel or retry the caller&#39;s own runs and attach citations to them. A token&#39;s <code>ns</code> claim limits which workflow namespaces it may run (live.*, wiki.*, ...). Quotas are checked before any provider call.</p>

POST /api/v1/templates/{key}/versions

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>

POST /api/v1/templates/{key}/versions/{version}/status

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
  • version (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>

GET /api/v1/usage

Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller's runs.

Capabilities
ai.usage.read
Visibility
internal
Response
application/json ai.usage-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.usage.read</strong> (internal): Read usage, quota windows, request logs, the audit log, cache statistics, the admin summary and any caller&#39;s runs.</p>

POST /api/v1/workflows/{key}/versions

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>

POST /api/v1/workflows/{key}/versions/{version}/status

Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled).

Capabilities
ai.workflow.manage
Visibility
internal
Parameters
  • key (path, required)
  • version (path, required)
Request body
application/json ai.definition-version-request@1
Response
application/json ai.definition-version-result@1
Errors
errors.problem@1 (application/problem+json)
Description<p><strong>ai.workflow.manage</strong> (internal): Create new versions of prompt templates, workflow definitions and routing profiles, and change their lifecycle status (draft, active, deprecated, archived; routes active/disabled). Every change is audited; edits never overwrite a version.</p>