API overview

Crevio exposes its entire AI-native platform as a REST API at https://api.crevio.co/v1. Use it to build custom websites, sync data with other systems, generate content, and run autonomous AI work. This page is the hub. For the rules every endpoint follows see Conventions; for failure handling see Errors; to get going fast see the Quickstart.

Authentication

Every request is authenticated with a bearer token sent in the Authorization header.

curl https://api.crevio.co/v1/products \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Create tokens in your dashboard under Settings → Developer. A token is shown once — store it in an environment variable or secrets manager, never in client-side code. Requests without a valid token get a 401. See the Quickstart for the full setup. Only admins of an account can use its API. Every request acts as the person behind the credential, and is refused with 403 account_forbidden when that person is not an admin of the account. An API key stops working once the person who created it is no longer an admin of the account.

Scopes

API keys and OAuth tokens share one set of scopes, checked the same way on the REST API, MCP and the AI gateway. Give each credential only the scopes its integration needs. A request outside them gets 403 insufficient_scope, with the missing scope in param and in the WWW-Authenticate header (Bearer error="insufficient_scope", scope="write"), so an OAuth client knows what to ask for when it reconnects. A scope is <resource>:<action>, or one of the two broad scopes read and write. There are three actions:

read sees data.
write creates, changes and deletes Crevio data, and includes read.
run makes something act for you: the agent, a script, a connected app or a model. No other scope includes a run scope.

Scope	Allows
`read`	Every `GET`, except the activity log and file downloads
`write`	Creating, changing and deleting resources, plus everything `read` allows
`agent:run`	Handing the agent work: `POST /chats`, `POST /chats/{id}/messages`, task run control, running a task, and the AI gateway’s `crevio` model
`scripts:run`	Script runs (`/script_runs`)
`models:run`	Raw models through the AI gateway
`connections:read`	Listing the team’s connections and their tools. `read` includes it
`connections:run`	Calling a connection’s tools (`/connections/{id}/execute` and `/proxy`)
`files:read`	Exchanging artifact ids for download links
`audit:read`	`GET /logs`

Work a credential starts can do no more than the credential itself. Without write, chats it starts run read-only (asking for another approval_mode is refused), it cannot continue, run or resume a task that can make changes, it cannot approve the agent’s pending actions, and its scripts cannot change anything. GET /me needs no scope. Keys made before scopes existed have scopes: null and keep full access until you set some. A key can grant only scopes it holds itself, so a narrow key cannot mint a wider one. OAuth clients ask for any of these scopes at authorization. Two shorthands from before they existed still work: read_only grants read, and read_write grants every scope. Discovery (scopes_supported) advertises only the shorthands, and a client that asks for nothing gets read_only. OAuth tokens cannot create API keys. A key is personal (the default) or team (kind: "team"). A personal key acts as you and sees your private chats and runs. A team key is for shared automations: it sees only what the whole account sees, the chats it starts are visible to the whole account, and it cannot run scripts. Edit a key’s name or scopes with PATCH /auth/keys/{id}; the change applies to its next request. POST /auth/keys/{id}/rotate issues a new secret and revokes the old one at the same moment, keeping the key’s id, name and scopes. GET /auth/keys lists team keys and your own personal keys, never other people’s. MCP clients connecting with a key see only the tools its scopes allow.

Handing the agent work

POST /chats gives the agent a job in plain language and returns its run. Pass wait_seconds (up to 90) to get the reply in the same response, in result; otherwise poll GET /task_runs/{id}, which carries result, json and artifacts once the run settles. Continue the conversation with POST /chats/{id}/messages.

curl https://api.crevio.co/v1/chats \
  -H "Authorization: Bearer $CREVIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-summary-2026-10-21" \
  -d '{
    "message": "How many orders did we get yesterday?",
    "wait_seconds": 60,
    "response_format": {"type": "json_schema", "json_schema": {"name": "orders", "schema": {"type": "object", "properties": {"count": {"type": "integer"}}, "required": ["count"]}}}
  }'

With a response_format, the agent is told the schema and its reply is parsed and validated: json holds the value, or json_error says why it did not match. json is never a value that fails the schema. Files the agent delivered during a run come back in artifacts. Exchange an artifact’s id for a download link at GET /artifacts/{id}/download_url; the link needs no credentials and expires after 15 minutes. POST /script_runs runs JavaScript on the account’s computer with no agent turn. args reach the script as the global args, and files it writes into the directory named by the global outputDir (20 at most, 50 MB each) come back as artifacts.

Reading the activity log

GET /logs returns the account’s append-only activity log, newest first: membership and permission changes, API keys, connections, approval decisions and, at the Full capture level, every app and tool the assistant uses. The log is part of the Enterprise plan; on other plans it returns 402 with the code plan_required. Filter with action, actor_type, entity_type, entity_id and after. It needs the audit:read scope, which read alone does not grant. How long events are kept is an account setting (30 to 730 days); see Security.

Base URL

https://api.crevio.co/v1

What you can build on

Crevio’s primitives span the whole business, not just commerce. Operations marked metered consume credits (see Usage & billing).

Primitive	What it does	Metered
Products & price variants	Sellable products and their pricing/billing models	—
Checkouts & checkout links	Create payment sessions; shareable buy links	—
Orders, invoices, refunds	The money lifecycle	—
Customers & subscriptions	Buyers, leads, and recurring billing	—
Discounts & reviews	Promo codes and social proof	—
Experiences	Course/content delivery (read-only)	—
Files & media generation	Uploads + AI images, video, audio	media gen
Sites & domains	AI website builder, domain purchase/connect	site builds
Email & socials	Broadcast email and multi-platform social posts	—
Web tools	Research, crawl, map, read, extract, search	yes
Tasks & task runs	Your scheduled AI workforce	yes
Calls & phone numbers	Autonomous AI phone calls	yes
Webhooks & events	React to platform events in real time	—
Usage	Plan, credit balance, and spend	—

Almost every operation here is also available to AI agents over MCP — you can script it, or just ask the agent to do it.

Core conventions, in brief

Unwrapped params — fields go at the top level, not under a resource key.
Associations — bare name + prefixed id (product: "prod_abc123", not product_id).
Money — integer cents, lowercase currency (amount: 4900, currency: "usd").
Lists — return { object: "list", data: [...], has_more }; single resources return the object directly.
IDs — prefixed strings (prod_, cus_, price_, ord_…) that encode the type.

The full rules — pagination, slug lookup, expand, delete responses, and the complete ID-prefix table — live in Conventions.

Errors

Failures return a JSON envelope you can branch on:

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Email can't be blank",
    "errors": { "email": ["can't be blank"] }
  }
}

See Errors for every status code and how to debug each.

Rate limiting

Crevio allows 600 requests per 60-second window per owner: all of one person’s keys and OAuth tokens on an account share it, and the account’s team keys share another. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; exceeding the limit returns 429 with code rate_limit_exceeded. Back off and retry using the X-RateLimit-Reset timing. See Rate limits for the full details.

The @crevio/sdk handles retries and backoff automatically.

TypeScript SDK

The official @crevio/sdk wraps the API with types, Zod validation, retries, and multi-runtime support (Node.js, browsers, Cloudflare Workers, Deno, Bun).

npm install @crevio/sdk

bun add @crevio/sdk

pnpm add @crevio/sdk

yarn add @crevio/sdk

import { Crevio } from "@crevio/sdk";

const crevio = new Crevio({ apiKeyAuth: "YOUR_API_TOKEN" });

const products = await crevio.products.list();
const product = await crevio.products.get({ id: "prod_abc123" });

const checkout = await crevio.checkouts.create({
  email: "customer@example.com",
  lineItems: [{ priceVariant: "price_xyz789", quantity: 1 }],
});

Next steps

Quickstart

Key to first call in under five minutes.

Conventions

The rules every endpoint follows.

Errors

Decode and fix every status code.

Usage & billing

How metered pay-per-call credits work.

Getting started

AI & agents

Core concepts

Integrations

Recipes

Authentication

Scopes

Handing the agent work

Reading the activity log

Base URL

What you can build on

Core conventions, in brief

Errors

Rate limiting

TypeScript SDK

Next steps

Quickstart

Conventions

Errors

Usage & billing

​Authentication

​Scopes

​Handing the agent work

​Reading the activity log

​Base URL

​What you can build on

​Core conventions, in brief

​Errors

​Rate limiting

​TypeScript SDK

​Next steps

Quickstart

Conventions

Errors

Usage & billing

Authentication

Scopes

Handing the agent work

Reading the activity log

Base URL

What you can build on

Core conventions, in brief

Errors

Rate limiting

TypeScript SDK

Next steps