---
title: "API reference"
description: "The public API endpoints — with a link to the machine-readable OpenAPI document."
slug: "en/developers/api-reference"
url: "https://docs.custom.one/en/developers/api-reference/"
capability: "integrations"
published_at: "2026-09-08T13:06:25.356Z"
---
Authenticate every request with a workspace API key, in either header:

```
Authorization: Bearer <key>
X-API-Key: <key>
```

The key prefix selects the host — `co_live_…` → `https://api.custom.one`,
`co_test_…` → `https://dev.api.custom.one`. All paths are under `/api/v1`.

## Endpoints

Grouped by what you are doing. This table is an index — the **contract** is the
OpenAPI document at the bottom of the page, generated from the API itself, and a
build check fails if the two ever disagree.

### Authentication

| Method & path | Purpose |
|---|---|
| `GET /me` | Test authentication. |

### Customs — read

| Method & path | Purpose |
|---|---|
| `GET /funnels` | List funnels of the workspace (for platform dropdowns). |
| `GET /funnels/:id` | One custom: its three version pointers, whether the draft has moved, and where a person opens it. |
| `GET /templates` | Templates you can clone. |
| `GET /funnels/:id/fields` | List a funnel’s mappable columns. |
| `GET /funnels/:id/readiness` | What still stands between this draft and a publish. |
| `GET /funnels/:id/questions` | The draft’s questions. |
| `GET /funnels/:id/scores` | The draft’s score definitions. |
| `GET /funnels/:id/segments` | The scenes: which clips exist and when each plays. |

### Customs — build and publish

| Method & path | Purpose |
|---|---|
| `POST /funnels` | Create a custom, optionally cloned from a template. |
| `PATCH /funnels/:id/questions` | REPLACE the question set. |
| `PATCH /funnels/:id/scores` | REPLACE the score set. |
| `PATCH /funnels/:id/segments` | REPLACE the scenes. |
| `POST /funnels/:id/clip-scripts` | Write the words a human will read on camera. |
| `POST /funnels/:id/pages/:pageSlug/html-blocks` | Add Custom HTML blocks to a result page, and get a link showing how it renders. Placement only — you write the HTML. |
| `POST /funnels/:id/result-page-previews` | See a draft result page for one set of answers, without publishing. Returns a link that expires. |
| `POST /funnels/:id/publish` | Take the draft live. |
| `DELETE /funnels/:id` | Move a custom to the trash. Soft — it stays recoverable from the dashboard. |

### Leads

| Method & path | Purpose |
|---|---|
| `GET /leads` | List the workspace’s leads, newest first. |
| `POST /leads` | Create a lead in a funnel (Action). |
| `PATCH /leads/:id` | Update a lead. |
| `GET /leads/sample` | Recent leads shaped like the diagnostic.submitted payload (for platform trigger tests). |
| `GET /tags` | List the workspace tags (for dropdowns). |
| `POST /leads/:id/tags` | Add tags (by name, created if missing) to the lead's contact. |
| `DELETE /leads/:id/tags` | Remove tags (by name) from the lead's contact. |

### Inbound sources

| Method & path | Purpose |
|---|---|
| `POST /sources` | Create a per-funnel inbound endpoint. |
| `GET /sources` | List a funnel’s inbound sources (never the secret). |
| `GET /sources/:id` | One inbound source (never the secret). |
| `PATCH /sources/:id` | Amend name, field mappings, active state or autoSubmit. |
| `DELETE /sources/:id` | Delete an inbound source. |
| `GET /sources/:id/secret` | Rebuild the ingest URL for an existing source. |
| `POST /sources/:id/rotate-secret` | Mint a new secret. |
| `POST /sources/:id/import` | Import CSV text as PENDING rows. |

### Outbound webhooks

| Method & path | Purpose |
|---|---|
| `POST /hooks` | Subscribe a REST hook (instant trigger). |
| `GET /hooks` | List API-created hooks of the workspace. |
| `PATCH /hooks/:id` | Change a subscription in place. |
| `DELETE /hooks/:id` | Unsubscribe a REST hook (dashboard-created webhooks are not reachable here). |

## Full reference

The complete, machine-readable contract — every parameter, response schema and
error — is the OpenAPI document, generated from the API itself:

- [`/openapi/public-openapi.json`](/openapi/public-openapi.json)

Point your code generator or AI agent at that URL. A rendered interactive
explorer is coming.