Skip to content

API reference

Create an API key

POST /v1/api-keys

Creates a scoped credential and returns its secret once.

Authentication
Send an API key or a service-account access token as a Bearer token.

Request body

PublicCreateApiKeyRequest

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

  • expiration null | ApiKeyExpiration Optional
  • expires_in_days integer | null Optional

    Requested lifetime in days; omission of both this field and `expiration` selects 90 days. It cannot be combined with `expiration`.

    Default
    • 90
    Minimum
    • 1
    Maximum
    • 365
  • monthly_spend_limit_microusd integer | null Optional

    Optional positive monthly spend ceiling in millionths of a US dollar.

    Minimum
    • 1
  • name string Required

    Human-readable key name.

    Minimum length
    • 1
    Maximum length
    • 100
  • permissions PublicApiKeyPermission[] Required

    Nonempty grants bounded by the caller's current effective permissions.

    Minimum items
    • 1

Responses

  • 201

    Key created; the secret is present only in this response.

    PublicCreatedApiKey X-Request-ID
  • 400

    Invalid request.

    PublicApiError X-Request-ID
  • 401

    Authentication required.

    PublicApiError X-Request-ID
  • 403

    Requested permissions exceed current authority.

    PublicApiError X-Request-ID
  • 409

    The account is unavailable or its active-key quota is exhausted.

    PublicApiError X-Request-ID

PublicCreatedApiKey

Public metadata for a newly issued API key.

  • created_at string Required

    Creation timestamp in UTC.

  • display_prefix string Required

    Non-secret prefix used to identify the key.

  • expires_at string | null Required

    Expiry timestamp in UTC, null for a key that never expires.

  • id string Required

    Stable credential id used for revocation.

  • name string Required

    User-provided display name.

  • secret string Required

    Plaintext secret present only in the creation response.

Schemas

ApiKeyExpiration

A named API-key lifetime: one day, one week, one month (30 days), one year (365 days), or a key that never expires.

Allowed values
  • 1d
  • 7d
  • 30d
  • 365d
  • never

ErrorCode

Machine-readable product API failure.

Allowed values
  • 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
VariantType
1object
2object

PublicApiError

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

  • code ErrorCode Required

    Closed status category suitable for program control flow.

    Allowed
    • unauthenticated
    • forbidden
    • invalid_request
    • not_found
    • conflict
    • payment_required
    • too_many_requests
    • upstream
    • internal
  • message string Required

    Safe diagnostic intended for operators, not program branching.

  • reason string Required

    Extensible machine-readable detail; clients must accept unknown values.

  • recovery null | ErrorRecovery Optional
  • request_id string | null Optional

    The request reference, equal to the response's `X-Request-ID`; quote it to support.

  • validation null | ValidationReport Optional

PublicApiKeyPermission

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

Allowed values
  • search-read
  • keys-create-own
  • keys-manage-own

ValidationIssue

One actionable, privacy-safe contract violation.

  • allowed_values array | null Optional
    Maximum items
    • 16
  • code string Required

    Stable, extensible machine-readable category.

    Maximum length
    • 64
  • path string Required

    RFC 6901 pointer to the rejected location; empty means the root value.

    Maximum length
    • 1024
  • suggestion string Required

    Code-owned instruction for correcting the request.

    Maximum length
    • 512

ValidationReport

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

  • contract string Required

    Stable contract name, normally the published schema component name.

    Maximum length
    • 128
  • issues ValidationIssue[] Required

    At most eight deterministic violations. Correct every issue before retrying.

    Maximum items
    • 8
  • truncated boolean Required

    Whether more violations were omitted; retry after correcting the listed issues.

Request 
curl --request POST "https://platform.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
Response 201 
{
  "created_at": "string",
  "display_prefix": "string",
  "expires_at": "string",
  "id": "string",
  "name": "string",
  "secret": "string"
}

Commands

No matching commands

Confirm it's you