Overview

The Stile API is a standard REST API: predictable resource URLs, JSON request and response bodies, conventional HTTP status codes, and Bearer-token authentication. Any language that can make HTTP requests can integrate — no SDK required. This page covers the conventions shared by every endpoint; the resource pages linked at the bottom document each endpoint in detail.

Base URL

https://api.stile.id/v1/

All endpoint paths in this reference are relative to this base. The API version (v1) is part of the URL path.

Authentication

Pass your secret key as a Bearer token in the Authorization header:

curl https://api.stile.id/v1/verification_sessions \
  -H "Authorization: Bearer stile_sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"

There are two kinds of keys:

Keys are managed at dashboard.stile.id/api-keys; secret keys are shown once at creation. There is one API environment, and every organization is live by default. To build and test without billing or a required webhook endpoint, ask Stile support to enable sandbox mode on a dedicated testing organization. Sandbox changes organization behavior, not the base URL or key format.

See Authentication for the full breakdown of key types and scopes.

Making a request

Here's the same API call — creating a verification session — in every supported language:

curl -X POST https://api.stile.id/v1/verification_sessions \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"type": "age", "workflow_id": "wf_YOUR_WORKFLOW_ID"}'

import requests

res = requests.post(
    "https://api.stile.id/v1/verification_sessions",
    headers={"Authorization": "Bearer stile_sk_..."},
    json={"type": "age", "workflow_id": "wf_YOUR_WORKFLOW_ID"},
)
session = res.json()

body := strings.NewReader(`{"type":"age","workflow_id":"wf_YOUR_WORKFLOW_ID"}`)
req, _ := http.NewRequest("POST", "https://api.stile.id/v1/verification_sessions", body)
req.Header.Set("Authorization", "Bearer stile_sk_...")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

const response = await fetch("https://api.stile.id/v1/verification_sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STILE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "age",
    workflow_id: "wf_YOUR_WORKFLOW_ID",
  }),
});
const session = await response.json();

Every session runs inside a published workflow — workflow_id is required, and the workflow carries the use case, jurisdictions, and verification methods. See Verification Sessions for the full parameter reference.

Request format

• Content-Type: application/json for all POST requests
• Query parameters: for GET requests and filtering

# POST — JSON body
curl -X POST https://api.stile.id/v1/verification_sessions \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"type": "age", "workflow_id": "wf_YOUR_WORKFLOW_ID"}'

# GET — query parameters
curl "https://api.stile.id/v1/verification_sessions?limit=10&status=verified" \
  -H "Authorization: Bearer stile_sk_..."

Response format

Responses are JSON. Every resource includes an object field identifying its type. Persistent objects also carry an id with a resource-specific prefix (vks_ for sessions, evt_ for events) and Unix-second timestamps (created, updated, expires_at, and so on):

{
  "id": "vks_abc123",
  "object": "verification_session",
  "status": "verified",
  "type": "age",
  "created": 1741564800
}

Pagination

List endpoints use cursor-based pagination:

starting_after and ending_before are mutually exclusive. Supplying both returns a 400 parameter_invalid response.

List responses share a common envelope with object: "list" and a has_more flag indicating whether more results exist:

{
  "object": "list",
  "url": "/v1/verification_sessions",
  "has_more": true,
  "data": [...]
}

To paginate forward, pass the last item's id as starting_after:

curl "https://api.stile.id/v1/verification_sessions?limit=10&starting_after=vks_abc123" \
  -H "Authorization: Bearer stile_sk_..."

Expanding responses

Some retrieve endpoints support expand[] to include related objects inline. A verification-session retrieve supports results and document expansions:

# Include verification results in the session response
curl "https://api.stile.id/v1/verification_sessions/vks_abc123?expand[]=results" \
  -H "Authorization: Bearer stile_sk_..."

The error object

API errors return a top-level error object. Core public routes return the complete structure below; a few older routes may omit type, code, param, or request_id, so treat those fields as optional:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "No such verification_session: 'vks_unknown'",
    "param": "id",
    "request_id": "req_abc123"
  }
}

Error types

HTTP status codes

Retry 429 (after Retry-After) and 5xx responses with exponential backoff — min(500ms * 2^attempt + jitter, 30s) is a good schedule. Never auto-retry other 4xx errors; fix the request instead. See Error Handling for resource-specific codes and recovery strategies.

Idempotency

POST requests accept an Idempotency-Key header to prevent duplicates:

curl -X POST https://api.stile.id/v1/verification_sessions \
  -H "Authorization: Bearer stile_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{"type": "age", "workflow_id": "wf_YOUR_WORKFLOW_ID"}'

Pick a key tied to the operation you're protecting (an order ID, a user ID plus action). The semantics:

• Same key, same body — the original response is replayed; no duplicate is created.
• Same key, different body — the request is rejected with 400 idempotency_key_reuse.

Send the same value in the Idempotency-Key header from every backend language.

Rate limiting

Requests are rate-limited per API key in fixed one-minute windows — 1,000 requests/minute for secret keys, 100/minute for publishable keys.

Authenticated requests processed by the rate limiter include these headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1741564920

When exceeded, the API returns 429 with a Retry-After header. Wait the specified seconds before retrying.

Node.js private preview

@stile/node is an unpublished private preview. Public integrations should use the HTTP contract documented here. If Stile has granted your organization package access, see the private-preview reference.

API playground

The core endpoints in this reference have interactive counterparts in the API Playground section of these docs, generated from Stile's OpenAPI spec (/openapi.yaml). Use it to explore request and response schemas alongside the prose reference here.

Explore the reference