API reference

Create an API key

Creates a scoped credential and returns its secret once.

POST /v1/api-keys

Request body

JSON body: PublicCreateApiKeyRequest

Request cURL

curl --request POST "https://yep.com/api/v1/api-keys" \
  --header "Authorization: Bearer $YEP_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "string",
  "permissions": [
    "search-read"
  ]
}
JSON

Responses

Response statuses

Status: 201
Description: Key created; the secret is present only in this response.
Body: PublicCreatedApiKey

Status: 400
Description: Invalid request.
Body: PublicApiError

Status: 401
Description: Authentication required.
Body: PublicApiError

Status: 403
Description: Requested permissions exceed current authority.
Body: PublicApiError

Status: 409
Description: The account is unavailable or its active-key quota is exhausted.
Body: PublicApiError

Schemas

ErrorCode

Machine-readable product API failure.

Request json

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

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

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

PublicApiKeyPermission

Stable permission names accepted by the public API-key endpoint.

Request json

[
  "search-read",
  "agent-run",
  "keys-create-own",
  "keys-manage-own"
]

PublicCreateApiKeyRequest

Stable public input for issuing a user-owned API key.

PublicCreateApiKeyRequest fields

Field: expires_in_days
Required: No
Type: integer | null
Description: Requested lifetime in days; omission selects 90 days.
Constraints: default: 90; min: 1; max: 365

Field: monthly_spend_limit_microusd
Required: No
Type: integer | null
Description: Optional positive monthly spend ceiling in millionths of a US dollar.
Constraints: min: 1

Field: name
Required: Yes
Type: string
Description: Human-readable key name.
Constraints: min length: 1; max length: 100

Field: permissions
Required: Yes
Type: PublicApiKeyPermission[]
Description: Nonempty grants bounded by the caller's current effective permissions.
Constraints: min items: 1

PublicCreatedApiKey

Public metadata for a newly issued API key.

PublicCreatedApiKey fields

Field: created_at
Required: Yes
Type: string
Description: Creation timestamp in UTC.
Constraints

Field: display_prefix
Required: Yes
Type: string
Description: Non-secret prefix used to identify the key.
Constraints

Field: expires_at
Required: Yes
Type: string
Description: Mandatory expiry timestamp in UTC.
Constraints

Field: id
Required: Yes
Type: string
Description: Stable credential id used for revocation.
Constraints

Field: name
Required: Yes
Type: string
Description: User-provided display name.
Constraints

Field: secret
Required: Yes
Type: string
Description: Plaintext secret present only in the creation response.
Constraints

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

Management