OPENAPI 3.1.0

API Reference

Vira Behavior API v0.1.0. Endpoint inventory, request schemas, response contracts, idempotency requirements, and deprecation state are read directly from the repository OpenAPI document.

AuthenticationAuthorization: Bearer <api-key>

Mutation retriesReuse the same Idempotency-Key

ScopePer-operation scopes are not declared in OpenAPI

AUTHORITY NOTE

Do not infer permission from an endpoint name.

The current OpenAPI document does not declare exact security scopes per operation. Runtime/control capability remains enforced by the API implementation and issued key policy. This reference therefore does not invent a scope label.

Read authentication & key guidance →

EXAMPLE

Resolve an exact behavior revision.

Placeholder credentials and IDs only. The body mirrors the required fields in the repository ResolveRequest schema.

curl -X POST "$VIRA_API_URL/v1/behavior/resolve" \
  -H "Authorization: Bearer <runtime-key>" \
  -H "Idempotency-Key: <stable-request-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project-uuid>",
    "applicationId": "<application-uuid>",
    "environment": "production",
    "behaviorPoint": "support.decision",
    "subjectId": "<application-subject-id>",
    "provider": "openai",
    "signals": { "issue_type": "delivery" }
  }'

RESOURCE

Api Keys

4 operations

GET/v1/api-keys

listApiKeys

Cursor page without secret material

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page without secret material

POST/v1/api-keys

createApiKey

Digest-backed API key; plaintext appears only on first execution

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Digest-backed API key; plaintext appears only on first execution

POST/v1/api-keys/{keyId}/rotate

rotateApiKey

Atomic replacement and revocation; plaintext appears only on first execution

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Atomic replacement and revocation; plaintext appears only on first execution

POST/v1/api-keys/{keyId}/revoke

revokeApiKey

Idempotent API key revocation

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Idempotent API key revocation

RESOURCE

Applications

2 operations

GET/v1/applications

listApplications

Cursor page of project applications

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of project applications

POST/v1/applications

createApplication

Idempotent tenant-scoped application creation

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Idempotent tenant-scoped application creation

RESOURCE

Approvals

4 operations

GET/v1/approvals

listApprovalRequests

Project-scoped approval queue

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Project-scoped approval queue

POST/v1/approvals

createApprovalRequest

Immutable action-bound approval request

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Immutable action-bound approval request

GET/v1/approvals/{requestId}

getApprovalRequest

Exact approval request and decision

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Exact approval request and decision

404Approval not found

POST/v1/approvals/{requestId}/decide

decideApprovalRequest

Action/revision-bound approval decision

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Action/revision-bound approval decision

409Approval expired, stale, or already settled

RESOURCE

Artifacts

1 operations

GET/v1/artifacts

listArtifacts

Cursor page of artifact metadata, digest, lineage, classification, and retention

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of artifact metadata, digest, lineage, classification, and retention

RESOURCE

Audit

1 operations

GET/v1/audit

listAudit

Cursor page of immutable project audit events

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of immutable project audit events

RESOURCE

Behavior

1 operations

POST/v1/behavior/resolve

resolveBehavior

Exact resolved revision with served deployment identity and optional exact shadow execution plan

Idempotency: Idempotency-Key required
Request: ResolveRequest · required
Scope: Not declared per-operation in OpenAPI

Responses

200Exact resolved revision with served deployment identity and optional exact shadow execution plan

RESOURCE

Behavior Points

3 operations

GET/v1/behavior-points/discover

discoverBehaviorPoints

Human-approval-required Behavior Point proposals from undeclared traces

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Human-approval-required Behavior Point proposals from undeclared traces

GET/v1/behavior-points

listBehaviorPoints

Cursor page of declared behavior points

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of declared behavior points

GET/v1/behavior-points/{key}

getBehaviorPoint

Declared Behavior Point with tenant-scoped metadata

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Declared Behavior Point with tenant-scoped metadata

404Behavior Point not found

RESOURCE

Behaviors

5 operations

GET/v1/behaviors

listBehaviors

Cursor page of behavior profiles and exact revision state

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of behavior profiles and exact revision state

GET/v1/behaviors/{profileId}/revisions

getBehaviorRevisionHistory

Immutable exact revision history for one behavior profile

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Immutable exact revision history for one behavior profile

GET/v1/behaviors/{profileId}/diff

diffBehaviorRevisions

Deterministic diff between two exact behavior revisions

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Deterministic diff between two exact behavior revisions

POST/v1/behaviors/{candidateId}/publish

publishBehaviorCandidate

Immutable behavior revision and exact deployment event

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Immutable behavior revision and exact deployment event

409Candidate did not pass the publication authority gate

POST/v1/behaviors/{profileId}/rollback

rollbackBehaviorProfile

New deployment event targeting an existing exact revision

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200New deployment event targeting an existing exact revision

RESOURCE

Candidates

4 operations

POST/v1/candidates/compile

compileCandidate

Candidate

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Candidate

GET/v1/candidates/{candidateId}

getCandidate

Project-scoped candidate

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Project-scoped candidate

PATCH/v1/candidates/{candidateId}

updateDraftCandidate

Updated draft candidate

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Updated draft candidate

409Candidate is no longer editable

POST/v1/candidates

createCandidate

Draft behavior candidate

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Draft behavior candidate

RESOURCE

Client Tokens

1 operations

POST/v1/client-tokens

issueClientToken

Short-lived application-bound feedback and Teach token

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Short-lived application-bound feedback and Teach token

RESOURCE

Deployments

6 operations

GET/v1/deployments

listDeployments

Cursor page of immutable deployment events

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of immutable deployment events

POST/v1/deployments

createDeployment

Deployment

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Deployment

PATCH/v1/deployments/{deploymentId}

retireDeployment

Rollout retired with an audit event

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Rollout retired with an audit event

POST/v1/deployments/canary-healthDeprecated

recordLegacyCanaryHealth

Legacy caller-supplied rollout decision

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Legacy caller-supplied rollout decision

POST/v1/deployments/{deploymentId}/comparisons

recordRolloutComparison

Immutable deployment-scoped comparison event

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Immutable deployment-scoped comparison event

409Comparison conflicts with exact rollout authority

POST/v1/deployments/{deploymentId}/authoritative-health

evaluateAuthoritativeRolloutHealth

Health decision computed from stored comparison events

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Health decision computed from stored comparison events

409Rollout baseline or comparison state drifted

503PostgreSQL authority required

RESOURCE

Documents

1 operations

POST/v1/documents

uploadTeachDocument

Durable artifact and human-review-required candidate suggestion

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Durable artifact and human-review-required candidate suggestion

RESOURCE

Evaluations

3 operations

POST/v1/evaluations

createEvaluation

Evaluation result

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Evaluation result

POST/v1/evaluations/{candidateId}

evaluateCandidate

Evaluation

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Evaluation

GET/v1/evaluations/{evaluationId}

getEvaluation

Project-scoped evaluation run

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Project-scoped evaluation run

RESOURCE

Exports

1 operations

POST/v1/exports/training-data

exportTrainingData

Immutable, revision-linked SFT, preference, and evaluation dataset artifact

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Immutable, revision-linked SFT, preference, and evaluation dataset artifact

RESOURCE

Feedback

1 operations

POST/v1/feedback

createFeedback

Feedback accepted

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Feedback accepted

RESOURCE

Integrations

1 operations

POST/v1/integrations/otel

ingestOtelSpan

Mapped trace

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Mapped trace

RESOURCE

Members

2 operations

GET/v1/members

listMembers

Cursor page of project members and roles

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of project members and roles

POST/v1/members

setMemberRole

Idempotent member creation or role update

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Idempotent member creation or role update

RESOURCE

Outcomes

1 operations

POST/v1/outcomes

createOutcome

Outcome accepted

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Outcome accepted

RESOURCE

Privacy

2 operations

POST/v1/privacy/jobs

createPrivacyJob

Idempotent BullMQ privacy operation

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Idempotent BullMQ privacy operation

GET/v1/privacy/jobs/{jobId}

getPrivacyJob

Project-scoped privacy job state and completion receipt

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Project-scoped privacy job state and completion receipt

RESOURCE

Projects

1 operations

GET/v1/projects/{projectId}

getProject

Tenant-scoped project metadata

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Tenant-scoped project metadata

RESOURCE

Service health

2 operations

GET/health

getLiveness

API process is alive

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200API process is alive

GET/ready

getReadiness

Authoritative persistence is ready

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Authoritative persistence is ready

503Authoritative persistence is unavailable

RESOURCE

Teach

3 operations

POST/v1/teach

createTeachEvidence

Evidence accepted

Idempotency: Idempotency-Key required
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Evidence accepted

GET/v1/teach/inbox

listTeachInbox

Cursor page

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page

GET/v1/teach/suggestions

listTeachSuggestions

Pattern suggestions

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Pattern suggestions

RESOURCE

Traces

2 operations

GET/v1/traces

listTraces

Cursor page

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page

POST/v1/traces

createTrace

Trace accepted

Idempotency: Idempotency-Key required
Request: TraceInput · required
Scope: Not declared per-operation in OpenAPI

Responses

200Trace accepted

RESOURCE

Usage

1 operations

GET/v1/usage

listUsage

Cursor page of immutable usage events and deterministic totals

Idempotency: Not declared for this operation
Request: No required JSON body
Scope: Not declared per-operation in OpenAPI

Responses

200Cursor page of immutable usage events and deterministic totals

LOADING DOCUMENTATION

Preparing this guide.

Documentation content remains server-rendered and crawlable; this state appears only while a route segment resolves.

curl -X POST "$VIRA_API_URL/v1/behavior/resolve" \ -H "Authorization: Bearer <runtime-key>" \ -H "Idempotency-Key: <stable-request-id>" \ -H "Content-Type: application/json" \ -d '{ "projectId": "<project-uuid>", "applicationId": "<application-uuid>", "environment": "production", "behaviorPoint": "support.decision", "subjectId": "<application-subject-id>", "provider": "openai", "signals": { "issue_type": "delivery" } }'