API reference

Run an agent

Runs the light or deep agent with the customer's configured provider key. Set background to return polling credentials immediately.

POST /v1/agent

Request body

JSON body: AgentRequest

Request cURL

curl --request POST "https://yep.com/api/v1/agent" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "mode": "light",
  "input": "Summarize the latest carbon border tax guidance.",
  "model": {
    "provider": "openrouter",
    "model": "anthropic/claude-sonnet-4.5"
  },
  "background": false
}
JSON

Responses

Response statuses

Status: 200
Description: Validated agent result.
Body: AgentRuntimeStatus

Status: 202
Description: Background run accepted; the proof is present only in this response.
Body: AgentRunCreated

Status: 400
Description: Invalid request.
Body: PublicApiError

Status: 401
Description: Authentication required.
Body: PublicApiError

Status: 402
Description: Agent API funds or a spend limit rejected execution.
Body: PublicApiError

Status: 403
Description: The API key lacks agent permission.
Body: PublicApiError

Status: 409
Description: No stored provider key can run the selected model; recovery includes the setup URL.
Body: PublicApiError

Status: 429
Description: The request exceeded a rate boundary.
Body: PublicApiError

Status: 500
Description: The service could not safely complete the operation.
Body: PublicApiError

Status: 502
Description: The agent runtime returned an invalid response.
Body: PublicApiError

Status: 503
Description: The agent is temporarily unavailable.
Body: PublicApiError

Status: 504
Description: A synchronous run exceeded five minutes.
Body: PublicApiError

Schemas

AgentEntrypoint

Closed product-facing program entrypoints.

Request json

[
  "light",
  "deep"
]

AgentModelRef

One allowlisted inference provider and model identifier.

AgentModelRef fields

Field: model
Required: Yes
Type: string
Description: Provider-native model identifier.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Closed provider discriminator.
Constraints

AgentRequest

One billed Agent API run.

AgentRequest fields

Field: background
Required: No
Type: boolean
Description: Return immediately with polling credentials instead of awaiting the result.
Constraints

Field: input
Required: Yes
Type: string
Description: Research request passed to the selected agent program.
Constraints: min length: 1; max length: 20000

Field: mode
Required: Yes
Type: AgentEntrypoint
Description: Execution depth for this run.
Constraints

Field: model
Required: Yes
Type: AgentModelRef
Description: Exact allowlisted provider/model pair selected for this run.
Constraints

AgentRunCreated

Background Agent API run accepted for polling.

AgentRunCreated fields

Field: id
Required: Yes
Type: string
Description: Non-secret run locator used for status polling.
Constraints

Field: session_secret
Required: Yes
Type: string
Description: Independent proof required together with the API key.
Constraints

AgentRuntimeFailure

Product-facing agent failure after runtime metadata has crossed the policy boundary.

AgentRuntimeFailure fields

Field: class
Required: Yes
Type: AgentRuntimeFailureClass
Description: Stable runtime failure class.
Constraints

Field: message
Required: Yes
Type: string
Description: Sanitized target-owned explanation.
Constraints

Field: reason
Required: Yes
Type: null | ErrorReason
Description
Constraints

Field: recovery
Required: Yes
Type: null | ErrorRecovery
Description
Constraints

AgentRuntimeFailureClass

Closed portable runtime failure classes.

Request json

[
  "rate_limited",
  "timeout",
  "transport",
  "invalid_output",
  "rejected",
  "internal"
]

AgentRuntimeState

Portable runtime lifecycle values.

Request json

[
  "queued",
  "running",
  "succeeded",
  "failed"
]

AgentRuntimeStatus

Product-facing terminal or in-progress status returned by agent APIs.

AgentRuntimeStatus fields

Field: agent_session_id
Required: Yes
Type: string
Description: Non-secret execution correlation id from the signed runtime session.
Constraints

Field: error
Required: Yes
Type: null | AgentRuntimeFailure
Description
Constraints

Field: output
Required: Yes
Type: null | Report
Description
Constraints

Field: program_digest
Required: Yes
Type: string
Description: Pinned semantic program digest.
Constraints

Field: state
Required: Yes
Type: AgentRuntimeState
Description: Closed runtime lifecycle state.
Constraints

Field: usage
Required: Yes
Type: UsageReport
Description: Provider usage accumulated so far.
Constraints

ErrorCode

Machine-readable product API failure.

Request json

[
  "unauthenticated",
  "forbidden",
  "invalid_request",
  "not_found",
  "conflict",
  "payment_required",
  "too_many_requests",
  "upstream",
  "internal"
]

ErrorReason

Stable product API failure reason.

Request json

[
  "malformed_request",
  "authentication_required",
  "reauthentication_required",
  "permission_denied",
  "api_key_name_invalid",
  "spend_policy_invalid",
  "rate_policy_invalid",
  "provider_key_invalid",
  "provider_key_missing",
  "agent_model_not_allowed",
  "resource_not_found",
  "state_conflict",
  "insufficient_funds",
  "spend_limit_exceeded",
  "rate_limit_exceeded",
  "model_provider_rate_limited",
  "model_provider_overloaded",
  "dependency_unavailable",
  "internal_failure"
]

ErrorRecovery

Browser-safe recovery action selected by the authoritative product boundary.

ErrorRecovery alternatives

Variant: 1
Type: object

Variant: 2
Type: object

Variant: 3
Type: object

ProviderKeyProvider

Closed provider set exposed to product clients.

Request json

[
  "openrouter"
]

PublicApiError

Stable public error envelope for APIs whose reason vocabulary is extensible.

PublicApiError fields

Field: agent_session_id
Required: No
Type: string | null
Description: Agent execution correlation id, present after an invocation is admitted.
Constraints

Field: code
Required: Yes
Type: ErrorCode
Description: Closed status category suitable for program control flow.
Constraints

Field: message
Required: Yes
Type: string
Description: Safe diagnostic intended for operators, not program branching.
Constraints

Field: reason
Required: Yes
Type: string
Description: Extensible machine-readable detail; clients must accept unknown values.
Constraints

Field: recovery
Required: No
Type: null | ErrorRecovery
Description
Constraints

Field: validation
Required: No
Type: null | ValidationReport
Description
Constraints

Report

UsageReport

ValidationIssue

One actionable, privacy-safe contract violation.

ValidationIssue fields

Field: allowed_values
Required: No
Type: array | null
Description
Constraints: max items: 16

Field: code
Required: Yes
Type: string
Description: Stable, extensible machine-readable category.
Constraints: max length: 64

Field: path
Required: Yes
Type: string
Description: RFC 6901 pointer to the rejected location; empty means the root value.
Constraints: max length: 1024

Field: suggestion
Required: Yes
Type: string
Description: Code-owned instruction for correcting the request.
Constraints: max length: 512

ValidationReport

Bounded validation feedback shared by model, REST, and MCP boundaries.

ValidationReport fields

Field: contract
Required: Yes
Type: string
Description: Stable contract name, normally the published schema component name.
Constraints: max length: 128

Field: issues
Required: Yes
Type: ValidationIssue[]
Description: At most eight deterministic violations. Correct every issue before retrying.
Constraints: max items: 8

Field: truncated
Required: Yes
Type: boolean
Description: Whether more violations were omitted; retry after correcting the listed issues.
Constraints

Agent