API overview

The Peki API lets your own software talk to your agents. Put your agent inside your app's chat screen, send it messages from your CRM, start an automation when your shop gets an order, or build your own website chat on top of an agent. This page is the map; each surface has its own page.

Base URL

https://peki.ai/api

Every path in these docs is relative to it. For example, POST /agents/{agentId}/sessions means:

POST https://peki.ai/api/agents/{agentId}/sessions

The one exception is incoming webhooks, which have their own full URL (see below).

The public API surfaces

Surface	What it's for	How it authenticates	Page
Sessions API	Chats from your own app: start a session per user, send messages, stream replies, upload files, rate and resolve.	API key	Sessions API
Files	Download a file from a conversation: a customer's photo, a document, a team reply's attachment.	API key	Files
Incoming webhooks	Let another system (Stripe, Shopify, GitHub, a form) start an automation the moment something happens there.	The secret webhook URL, plus an optional signature	Incoming webhooks
Website chat API	The public endpoints behind the website chat, for building your own chat UI in a browser.	The widget's public key and a visitor id	Website chat API

note

API keys authenticate the same API that the Peki dashboard itself uses, but only the endpoints documented here are the public API. Other endpoints are made for the Peki dashboard's own screens and can change without notice. Build only on what's documented here.

Before you start

1. Publish your agent. Customers, and your API calls, always talk to the published version. Publishing needs a paid plan. See Publishing and versions.
2. Create an API key in Settings → API keys (admins). Use Read and write to send messages, Read only to only read. See API keys.
3. Find your agent's id. Open the agent in Peki; the id is the part of the address after /agents/. In https://peki.ai/agents/66f1c2a9e4b0a1d2c3e4f567/instructions the id is 66f1c2a9e4b0a1d2c3e4f567.

Then make your first call:

curl https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions \
  -H "Authorization: Bearer psk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"customer": {"id": "user-1042", "name": "Maria Lopez"}}'

Conventions

Requests

• Send JSON bodies with Content-Type: application/json, except file uploads, which are multipart/form-data.
• Ids are 24-character hexadecimal strings, like 66f1c2a9e4b0a1d2c3e4f567.
• Unknown fields in a body are ignored, except where a page says the body is strict.

Responses

• Responses are JSON, except file downloads and streams.
• Times are ISO 8601 in UTC, like 2026-10-26T14:03:11.520Z.
• Optional fields are left out when they have no value, rather than sent as null.

Errors

Errors use HTTP status codes and a JSON body with a human-readable message. Some errors add a machine-readable code; check code when there is one, because the message text can change.

A validation error lists what's wrong in issues (shortened here):

{
  "message": "Invalid body",
  "issues": [
    { "path": ["customer", "id"], "message": "Too small: expected string to have >=1 characters" }
  ]
}

A typical other error:

{ "statusCode": 404, "message": "Session not found", "error": "Not Found" }

Status	Meaning
400	The request is malformed or a field is invalid.
401	No credential, or the key is invalid or revoked.
402	Credits or plan: credits_exhausted or plan_required.
403	The key doesn't have the access this needs, or the endpoint is for people only.
404	The thing doesn't exist in your workspace.
409	The request conflicts with the current state, for example the agent isn't published.
413	A file or body is too large.
429	Too many requests. Wait and retry.
503	We couldn't accept the request right now. Retry shortly.

Retries

Retry 429 and 503 with a growing delay (for example 1 s, 2 s, 4 s). Don't retry 4xx errors other than 429 without changing the request.

What it costs

Agent replies to sessions you start through the API use credits like replies on any other channel, shown as Agent replies in your usage. Live replies are never refused for credits. See Plans and credits.

Related

• Authentication
• Sessions API
• Files
• Incoming webhooks
• Website chat API
• API keys