{ "openapi": "3.1.0", "info": { "title": "Revnu API", "version": "2026-10-22", "summary": "Read and approve your Revnu growth agent's review queue, message it, and pull results.", "description": "Revnu runs GTM on autopilot for software businesses. This API is the agent's front door: nothing sends, publishes or spends except through the same approvals the dashboard uses. Full docs: https://revnu.com/docs (markdown index at https://revnu.com/docs/llms.txt).", "termsOfService": "https://revnu.com/terms", "contact": { "name": "Revnu", "url": "https://revnu.com/contact" } }, "externalDocs": { "description": "Revnu Docs", "url": "https://revnu.com/docs" }, "servers": [ { "url": "https://revnu.com" } ], "tags": [ { "name": "API Reference", "description": "The personal-token API at /api/v1: review queue, agent, results, workflows, leads, LinkedIn lookups and the block list, plus the no-token website preview." }, { "name": "Content API", "description": "Read-only JSON for the posts Revnu publishes, for rendering a blog on your own site." }, { "name": "Measurement", "description": "Server-side conversion events, tied back to the visit that brought the customer." } ], "paths": { "/api/v1/me": { "get": { "operationId": "me", "summary": "Get the current token", "description": "Who this token is: label, scopes, the account it belongs to, whether the account is still in setup, and the rate limits it is held to. Needs no scope.\n\n**Response.** ```json\n{\n \"me\": {\n \"tokenId\": \"…\",\n \"label\": \"wall dashboard\",\n \"scopes\": [\"review:read\", \"review:write\"],\n \"createdAt\": 1789837627802,\n \"lastUsedAt\": 1789851456304,\n \"account\": { \"id\": \"…\", \"name\": \"Acme\" },\n \"inSetup\": false,\n \"limits\": {\n \"reads\": { \"perMinute\": 300, \"burst\": 600 },\n \"writes\": { \"perMinute\": 60, \"burst\": 120 },\n \"messages\": { \"perMinute\": 30, \"burst\": 60 },\n \"account\": { \"perMinute\": 900, \"burst\": 1800 }\n }\n }\n}\n```\n\n`lastUsedAt` and `account.name` can be `null`. `inSetup` is `true` while a self-serve account hasn't finished [setup](/docs/setup-status); until its trial starts, every other route except the setup routes answers `402 setup_pending`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/me" }, "security": [ { "personalToken": [] } ], "responses": { "200": { "description": "{ me }", "content": { "application/json": { "schema": { "type": "object", "properties": { "me": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "createdAt": { "type": "number" }, "inSetup": { "type": "boolean" }, "label": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "limits": { "type": "object", "properties": { "account": { "type": "object", "properties": { "burst": { "type": "number" }, "perMinute": { "type": "number" } }, "required": [ "burst", "perMinute" ] }, "messages": { "type": "object", "properties": { "burst": { "type": "number" }, "perMinute": { "type": "number" } }, "required": [ "burst", "perMinute" ] }, "reads": { "type": "object", "properties": { "burst": { "type": "number" }, "perMinute": { "type": "number" } }, "required": [ "burst", "perMinute" ] }, "writes": { "type": "object", "properties": { "burst": { "type": "number" }, "perMinute": { "type": "number" } }, "required": [ "burst", "perMinute" ] } }, "required": [ "account", "messages", "reads", "writes" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "tokenId": { "type": "string" } }, "required": [ "account", "createdAt", "inSetup", "label", "lastUsedAt", "limits", "scopes", "tokenId" ] } }, "required": [ "me" ] } } } }, "401": { "description": "Missing, unknown or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the read limit; wait Retry-After seconds", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review": { "get": { "operationId": "reviewList", "summary": "List the review queue", "description": "What is waiting for the customer's approval, each card carrying the verbs it offers and the label for its main button. LinkedIn and gift cards list approve but are approved in the dashboard only.\n\nRequires the `review:read` scope.\n\n**Response.** `{ \"items\": [card, …] }`, newest first within priority band. A card:\n\n```json\n{\n \"id\": \"k97…\",\n \"kind\": \"approval\",\n \"sourceType\": \"gmail_draft\",\n \"status\": \"pending\",\n \"title\": \"Reply to Priya at Acme\",\n \"prompt\": \"…\",\n \"summary\": \"…\",\n \"detail\": null,\n \"priority\": \"high\",\n \"options\": null,\n \"textInput\": null,\n \"budgetChange\": null,\n \"payload\": { \"…\": \"the draft, the research; long text capped at 8 KB\" },\n \"actions\": [\"send\", \"snooze\", \"dismiss\"],\n \"primaryLabel\": \"Send Reply\",\n \"autoResolveAt\": 1758326400000,\n \"dueAt\": null, \"snoozedUntil\": null,\n \"leadId\": \"…\", \"leadContactId\": null, \"postId\": null,\n \"createdAt\": 1758240000000, \"updatedAt\": 1758240000000, \"resolvedAt\": null, \"resolution\": null\n}\n```\n\n`actions` lists the verbs the card offers right now. Drive your UI from `actions` and `primaryLabel`; see [Build a Review Screen](/docs/build-a-review-screen). Which verbs send or publish is on [Answer a card](/docs/review-answer#what-approve-does) and [Send an email card](/docs/review-send).\n\n**LinkedIn invites and messages** (`linkedin_invite`, `linkedin_message`) and **gifts** (`gift_send`) are approved only on the Review page in the dashboard, so their `actions` never include `approve`. `primaryLabel` still names the dashboard button, so a UI can link there. The refusals are listed under [Answer a card](/docs/review-answer#what-approve-does).\n\nA card that waits seven days without an answer expires and leaves the queue, unless it was set to ship on its own at `autoResolveAt`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-list" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "pending or needs_revision. Default: both.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 100. Default 50.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{ \"items\": [card, …] }, newest first within priority band. A card: ``json { \"id\": \"k97…\", \"kind\": \"approval\", \"sourceType\": \"gmail_draft\", \"status\": \"pending\", \"title\": \"Reply to Priya at Acme\", \"prompt\": \"…\", \"summary\": \"…\", \"detail\": null, \"priority\": \"high\", \"options\": null, \"textInput\": null, \"b", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewCardWire" } } }, "required": [ "items" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}": { "get": { "operationId": "reviewGet", "summary": "Get one card", "description": "Retrieve a Revnu review card by ID in any status. Read its full draft payload, resolution and resolved time with the review:read API token scope.\n\nRequires the `review:read` scope.\n\n**Response.** `{ \"item\": card }` with the same shape as [the list](/docs/review-list). Unlike the list, this returns a card in any status, so you can read how one was resolved: `resolvedAt` and `resolution`. `404` for an unknown id or another account's id; the two are indistinguishable on purpose.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-get" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"item\": card } with the same shape as the list. Unlike the list, this returns a card in any status, so you can read how one was resolved: resolvedAt and resolution. 404 for an unknown id or another account's id; the two are indistinguishable on purpose.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/ReviewCardWire" } }, "required": [ "item" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/search": { "get": { "operationId": "reviewSearch", "summary": "Search review history", "description": "Check existing work for several people or topics in one request, including resolved cards, without returning full drafts.\n\nRequires the `review:read` scope.\n\n**Response.** ```json\n{\n \"matches\": [{\n \"query\": \"Acme\",\n \"hasMore\": false,\n \"openCardCount\": 0,\n \"items\": [{\n \"id\": \"k97…\",\n \"title\": \"Reply to Acme\",\n \"status\": \"done\",\n \"sourceType\": \"agent\",\n \"updatedAt\": 1792400000000,\n \"resolvedAt\": 1792400000000,\n \"resolutionAction\": \"approve\",\n \"delivery\": \"unconfirmed\",\n \"reviewUrl\": \"https://revnu.com/dashboard/review…\"\n }]\n }],\n \"coverage\": \"Search coverage and delivery evidence limitations.\"\n}\n```\n\nSearch matches are bounded by relevance, combined across title and prompt,\nthen ordered by update time. `hasMore` means matches may be missing because the\nresult limit or the batch's shared read budget stopped the search. Later names\ncan return no items with `hasMore: true`; that is incomplete evidence. An\nempty list means no matching title or prompt, not that no work or send exists.\n\n`status` describes the card. A done card does not prove delivery.\n`sent_recorded` means the card's resolution records a send. `queued` means\napproved for delivery. Other resolutions return `unconfirmed`. This endpoint\ndoes not check the provider for a receipt.\n\nDraft bodies and internal payloads are omitted. [Get a card](/docs/review-get)\nreturns the full details. Reading history does not change any card or send a\nmessage. Responses are not cached.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-search" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:read", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Repeat for each person or topic. Required: 1 to 10 queries, each 1 to 120 characters. Searches card titles and prompts across all statuses.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum matches per query, from 1 to 20. Default 5.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "``json { \"matches\": [{ \"query\": \"Acme\", \"hasMore\": false, \"openCardCount\": 0, \"items\": [{ \"id\": \"k97…\", \"title\": \"Reply to Acme\", \"status\": \"done\", \"sourceType\": \"agent\", \"updatedAt\": 1792400000000, \"resolvedAt\": 1792400000000, \"resolutionAction\": \"approve\", \"delivery\": \"unconfirmed\", \"reviewUrl\": \"", "content": { "application/json": { "schema": { "type": "object", "properties": { "coverage": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "delivery": { "type": "string", "enum": [ "queued", "sent_recorded", "unconfirmed" ] }, "id": { "type": "string" }, "resolutionAction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolvedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "reviewUrl": { "type": "string" }, "sourceType": { "type": [ "string", "null" ], "enum": [ "ads_budget", "ads_launch", "agent", "blog_draft", "blog_edit", "booking_link", "gift_send", "gmail_draft", "gmail_reply", "lead", "lead_contact", "linkedin_invite", "linkedin_message", "measurement_charter", "memory_rule", "outbound_setup", "outreach_sequence", "reddit_comment", "system", null ] }, "status": { "type": "string", "enum": [ "cancelled", "dismissed", "done", "expired", "needs_revision", "pending", "snoozed" ] }, "title": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "delivery", "id", "resolutionAction", "resolvedAt", "reviewUrl", "sourceType", "status", "title", "updatedAt" ] } }, "openCardCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "query": { "type": "string" } }, "required": [ "hasMore", "items", "openCardCount", "query" ] } } }, "required": [ "coverage", "matches" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}/answer": { "post": { "operationId": "reviewAnswer", "summary": "Answer a card", "description": "Resolve a card the way the dashboard's primary button would: approve, answer a question, or choose an option.\n\nRequires the `review:write` scope.\n\n**Response.** | Code | Meaning |\n|---|---|\n| 200 | `{ ok, kind, result? }` |\n| 409 | `invalid_action` with the current `actions`, `rejected` with a `message`, or `use_send` for an email card |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-answer" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "| Field | Type | Meaning |\n|---|---|---|\n| `action` | `approve`, `answer` or `choose` | Must be in the card's `actions`. |\n| `text` | string, up to 8,000 UTF-8 bytes | For `answer`, and optionally with `approve`. |\n| `optionValues` | string[] | For `choose`: exactly one of the card's option values. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ ok, kind, result? }", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "blog_edit_applied" }, "ok": { "type": "boolean", "const": true } }, "required": [ "kind", "ok" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "blog_published" }, "ok": { "type": "boolean", "const": true }, "result": { "$ref": "#/components/schemas/PublishResult" } }, "required": [ "kind", "ok", "result" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "outbound_setup" }, "ok": { "type": "boolean", "const": true }, "result": { "type": "object", "properties": { "approvedAt": { "type": "number" }, "createdAt": { "type": "number" }, "plan": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "mailboxes": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "senderFirstName": { "type": "string" }, "senderLastName": { "type": "string" } }, "required": [ "address", "senderFirstName" ] } } }, "required": [ "domain", "mailboxes" ] } }, "initialDailyLimit": { "type": "number" }, "linkTracking": { "type": "boolean" }, "openTracking": { "type": "boolean" }, "orderType": { "type": "string", "const": "extra_accounts" }, "placementChecking": { "type": "boolean" }, "redirectUrl": { "type": "string" }, "sendingWindow": { "type": "object", "properties": { "endHour": { "type": "number" }, "startHour": { "type": "number" }, "timeZone": { "type": "string" } }, "required": [ "endHour", "startHour", "timeZone" ] }, "warmup": { "type": "boolean" } }, "required": [ "domains", "initialDailyLimit", "linkTracking", "openTracking", "placementChecking", "redirectUrl", "warmup" ] }, "progressAt": { "type": "number" }, "proposalId": { "type": "string" }, "readinessNotificationSent": { "type": "boolean" }, "reviewItemId": { "type": "string" }, "revision": { "type": "number" }, "status": { "type": "string", "enum": [ "cancelled", "ready", "revnu_attention_required", "setting_up", "waiting_for_approval", "warming" ] }, "updatedAt": { "type": "number" } }, "required": [ "createdAt", "plan", "progressAt", "proposalId", "readinessNotificationSent", "reviewItemId", "revision", "status", "updatedAt" ] } }, "required": [ "kind", "ok", "result" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "resolved" }, "ok": { "type": "boolean", "const": true } }, "required": [ "kind", "ok" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "invalid_action with the current actions, rejected with a message, or use_send for an email card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}/send": { "post": { "operationId": "reviewSend", "summary": "Send an email card", "description": "Approve and send an email draft or reply Revnu wrote, optionally with an edited reply body. This sends real email.\n\nRequires the `review:write` scope.\n\n**Response.** `200 { \"ok\": true, \"data\": { \"outcome\": \"sent\", \"queued\": false, \"messageId\": \"\" } }` once the provider accepted it; `messageId` is the delivery receipt. When the mailbox paces its sending, the email is queued instead: `data` has `queued: true` and, once the queue has placed it, `leavesAt` (ISO 8601) and `timing`. A provider refusal is also a `200`, as `{ \"ok\": false, \"error\": { \"kind\", \"detail\" } }`; `kind` is one of `rate_limited`, `out_of_credits`, `not_found`, `network`, `upstream_5xx`, `schema_drift`, `bad_input`, `missing_key` or `budget_exhausted`. The full shape is in [/openapi.json](/openapi.json). `409` if the card was already handled or is not an email card. `503 delivery_pending` with a `Retry-After` header if the provider's answer was lost: the send is fenced for reconciliation rather than risked twice, so wait and retry the same call. `503 unavailable`, also with `Retry-After`, when the delivery service could not be reached.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-send" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "| Field | Meaning |\n|---|---|\n| `body` | Optional, replies (`gmail_reply`) only. Send this text instead of the draft. Cannot be empty if present. A `body` on a `gmail_draft` card is a `400`: a draft always sends the copy that was reviewed. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "200 { \"ok\": true, \"data\": { \"outcome\": \"sent\", \"queued\": false, \"messageId\": \"\" } } once the provider accepted it; messageId is the delivery receipt. When the mailbox paces its sending, the email is queued instead: data has queued: true and, once the queue has placed it, leavesAt (ISO 8601) and ", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "alreadyQueued": { "type": "boolean" }, "alreadySent": { "type": "boolean" }, "approvedBy": { "type": "string", "enum": [ "customer", "sequence", "setting" ] }, "deduped": { "type": "boolean" }, "detail": { "type": "string" }, "draftId": { "type": "string" }, "leavesAt": { "type": "string" }, "messageId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "awaiting_approval", "held", "queued", "sent" ] }, "queued": { "type": "boolean" }, "reviewItemId": { "type": "string" }, "review_item_id": { "type": "string" }, "sendAtLocal": { "type": "string" }, "sendsAtLocal": { "type": "string" }, "shipsAt": { "type": "number" }, "threadId": { "type": "string" }, "timing": { "type": "string" } }, "required": [ "queued" ] }, "ok": { "type": "boolean", "const": true }, "usage": { "$ref": "#/components/schemas/ProviderUsage" } }, "required": [ "data", "ok" ] }, { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/OutreachError" }, "ok": { "type": "boolean", "const": false }, "usage": { "$ref": "#/components/schemas/ProviderUsage" } }, "required": [ "error", "ok" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}/request-changes": { "post": { "operationId": "reviewRequestChanges", "summary": "Request changes", "description": "Send a card back to the agent with feedback. A revised version returns to the queue.\n\nRequires the `review:write` scope.\n\n**Response.** `200 { ok: true }`. `409 invalid_action` if the card no longer accepts it.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-request-changes" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "`text`, required, up to 8,000 UTF-8 bytes. The agent starts revising about 30 seconds later; the card sits in `needs_revision` until the new version comes back for review.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "200 { ok: true }. 409 invalid_action if the card no longer accepts it.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}/snooze": { "post": { "operationId": "reviewSnooze", "summary": "Snooze a card", "description": "Snooze a Revnu review card until a future timestamp through the API. Hide it from review and cancel its auto-ship deadline with the review:write scope.\n\nRequires the `review:write` scope.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-snooze" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "`until`, epoch milliseconds, in the future. Snoozing cancels the trust ladder's `autoResolveAt` so nothing ships while you are not looking.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/review/{id}/dismiss": { "post": { "operationId": "reviewDismiss", "summary": "Dismiss a card", "description": "Decline a card. It closes without shipping, the agent's trust for that kind of work resets, and the reason teaches it.\n\nRequires the `review:write` scope.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/review-dismiss" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "review:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "`reason`, optional, up to 2,000 characters. Outbound-setup cards also cancel their proposal.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/messages": { "post": { "operationId": "agentMessages", "summary": "Send a message", "description": "Message your agent exactly as the dashboard chat does, and optionally hold the request open for the reply.\n\nRequires the `agent:message` scope.\n\n**Response.** | Code | Meaning |\n|---|---|\n| 202 | `{ requestId, deduplicated, notSent?, message? }`. Queued; poll [the message](/docs/agent-message-status). With `waitSeconds`, `message` is the last state seen, and `waitEnded` (`unauthorized` or `poll_failed`) says when the wait stopped early. An `unauthorized` stop carries no `message`. |\n| 200 | Only with `waitSeconds`: `message` is terminal and `replies` is filled. |\n| 400 | Missing or empty `text`, `text` over 8,000 bytes, a non-string client id, a non-boolean `interrupt` or `queue`, `queue` together with `interrupt`, or a `waitSeconds` outside 0 to 120. |\n| 409 | `rejected` with a `message`: `text` over 4,000 characters, a client id with characters outside `A-Za-z0-9_.:-`, or an account that can't take work right now (a trial waiting for a card, or paused for payment). |\n\nWith `interrupt: false` and an unfinished earlier message, either code can carry `notSent: true`: `requestId` and `message` are then the earlier request's, and nothing new was sent.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/agent-messages" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "agent:message", "requestBody": { "required": true, "description": "| Field | Type | Meaning |\n|---|---|---|\n| `text` | string, required | Up to 4,000 characters. See [Message length](#message-length). |\n| `clientRequestId` | string | Up to 128 characters of `A-Za-z0-9_.:-`. A retry with the same id returns the original `requestId`. Never reuse an id after a `failed` message; send again with a new one. |\n| `waitSeconds` | integer, 0 to 120 | Hold the request until the message is `done`: the agent replied or failed and any background research it started was reported. |\n| `interrupt` | boolean, default `true` | A new message stops the agent's running turn. Send `false` to leave unfinished work alone: while this token's newest message is still queued or running, nothing is sent and the response names that request with `notSent: true`. |\n| `queue` | boolean, default `false` | Send `true` to hand over another job without stopping the running one: the message is sent and the agent starts it once its current work is done. Use it when your software sends several jobs in a row, such as one list of companies per market. It stays `queued` for up to six hours while earlier work runs, then counts as `failed`. Cannot be combined with `interrupt`. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Only with waitSeconds: message is terminal and replies is filled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "message": { "anyOf": [ { "type": "object", "properties": { "backgroundTasks": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundTask" } }, "done": { "type": "boolean" }, "failure": { "type": "string" }, "interrupted": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "text": { "type": "string" } }, "required": [ "at", "text" ] } }, "requestId": { "type": "string" }, "sentAt": { "type": "number" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "text": { "type": "string" } }, "required": [ "backgroundTasks", "done", "replies", "requestId", "sentAt", "status", "text" ] }, { "type": "null" } ] }, "notSent": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "deduplicated", "message", "requestId" ] } } } }, "202": { "description": "{ requestId, deduplicated, notSent?, message? }. Queued; poll the message. With waitSeconds, message is the last state seen, and waitEnded (unauthorized or poll_failed) says when the wait stopped early. An unauthorized stop carries no message.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "message": { "anyOf": [ { "type": "object", "properties": { "backgroundTasks": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundTask" } }, "done": { "type": "boolean" }, "failure": { "type": "string" }, "interrupted": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "text": { "type": "string" } }, "required": [ "at", "text" ] } }, "requestId": { "type": "string" }, "sentAt": { "type": "number" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "text": { "type": "string" } }, "required": [ "backgroundTasks", "done", "replies", "requestId", "sentAt", "status", "text" ] }, { "type": "null" } ] }, "notSent": { "type": "boolean" }, "requestId": { "type": "string" }, "waitEnded": { "type": "string", "const": "poll_failed" } }, "required": [ "deduplicated", "requestId", "waitEnded" ] }, { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "message": { "anyOf": [ { "type": "object", "properties": { "backgroundTasks": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundTask" } }, "done": { "type": "boolean" }, "failure": { "type": "string" }, "interrupted": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "text": { "type": "string" } }, "required": [ "at", "text" ] } }, "requestId": { "type": "string" }, "sentAt": { "type": "number" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "text": { "type": "string" } }, "required": [ "backgroundTasks", "done", "replies", "requestId", "sentAt", "status", "text" ] }, { "type": "null" } ] }, "notSent": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "deduplicated", "requestId" ] }, { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "notSent": { "type": "boolean" }, "requestId": { "type": "string" }, "waitEnded": { "type": "string", "const": "unauthorized" } }, "required": [ "deduplicated", "requestId", "waitEnded" ] }, { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "notSent": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "deduplicated", "requestId" ] } ] } } } }, "400": { "description": "Missing or empty text, text over 8,000 bytes, a non-string client id, a non-boolean interrupt or queue, queue together with interrupt, or a waitSeconds outside 0 to 120.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "rejected with a message: text over 4,000 characters, a client id with characters outside A-Za-z0-9_.:-, or an account that can't take work right now (a trial waiting for a card, or paused for payment).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/messages/{requestId}": { "get": { "operationId": "agentMessageStatus", "summary": "Poll a message", "description": "One message's status and every reply the agent has sent since it landed.\n\nRequires the `agent:message` scope.\n\n**Response.** ```json\n{\n \"message\": {\n \"requestId\": \"f2a283fd-…\",\n \"status\": \"replied\",\n \"done\": true,\n \"text\": \"What did we ship this week?\",\n \"sentAt\": 1789851456304,\n \"replies\": [{ \"text\": \"Three things shipped: …\", \"at\": 1789851468121 }],\n \"backgroundTasks\": []\n }\n}\n```\n\n`status` is `queued`, `running`, `replied` or `failed` (with a `failure` message; re-send with a new client id). `replied` means the agent answered and finished the turn. The agent may answer in more than one bubble, and it often posts progress while it works, so `replies` can fill while the status is still `running`. It is a list, oldest first, holding the latest five bubbles. `interrupted: true` means a later message stopped this turn before it finished.\n\nLong research, such as building a list of 50 companies, runs as a background task: the agent replies that it has started, its turn ends with `status: \"replied\"`, and the research carries on. `backgroundTasks` lists each task the message started with its `id`, `label`, `state` (`running`, `done`, `failed` or `stopped`), `startedAt` and `endedAt`. A task is `done` once the agent has checked and saved its results and reported them, and that report joins `replies` (the latest ten bubbles). `done` on the message is `true` only when the turn has ended and no task is still running, so wait for `done`, not for `replied`. `404` for an unknown id, a colleague's dashboard turn, or another account's message.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/agent-message-status" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "agent:message", "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "``json { \"message\": { \"requestId\": \"f2a283fd-…\", \"status\": \"replied\", \"done\": true, \"text\": \"What did we ship this week?\", \"sentAt\": 1789851456304, \"replies\": [{ \"text\": \"Three things shipped: …\", \"at\": 1789851468121 }], \"backgroundTasks\": [] } } ` status is queued, running, replied or failed (with ", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "backgroundTasks": { "type": "array", "items": { "$ref": "#/components/schemas/BackgroundTask" } }, "done": { "type": "boolean" }, "failure": { "type": "string" }, "interrupted": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "text": { "type": "string" } }, "required": [ "at", "text" ] } }, "requestId": { "type": "string" }, "sentAt": { "type": "number" }, "status": { "$ref": "#/components/schemas/MessageStatus" }, "text": { "type": "string" } }, "required": [ "backgroundTasks", "done", "replies", "requestId", "sentAt", "status", "text" ] } }, "required": [ "message" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/thread": { "get": { "operationId": "agentThread", "summary": "Read the thread", "description": "Read your API token's conversation with the Revnu agent, newest first. Retrieve message text, roles, timestamps and request IDs to rebuild conversation history.\n\nRequires the `agent:message` scope.\n\n**Response.** `{ \"items\": [{ role, requestId, text, at }, …] }` with `role` of `user` or `agent`. Each token is its own thread; dashboard and Slack conversations are not included. A bot can rebuild its history from here after a restart, matching its own messages by `requestId`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/agent-thread" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "agent:message", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "1 to 100. Default 50.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{ \"items\": [{ role, requestId, text, at }, …] } with role of user or agent. Each token is its own thread; dashboard and Slack conversations are not included. A bot can rebuild its history from here after a restart, matching its own messages by requestId.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "number" }, "requestId": { "type": "string" }, "role": { "type": "string", "const": "agent" }, "text": { "type": "string" } }, "required": [ "at", "requestId", "role", "text" ] }, { "type": "object", "properties": { "at": { "type": "number" }, "requestId": { "type": "string" }, "role": { "type": "string", "const": "user" }, "text": { "type": "string" } }, "required": [ "at", "requestId", "role", "text" ] } ] } } }, "required": [ "items" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/agent/status": { "get": { "operationId": "agentStatus", "summary": "Get agent status", "description": "Whether the agent is up and busy: sandbox state, last activity, and the next scheduled wake.\n\nRequires the `results:read` scope.\n\n**Response.** ```json\n{ \"status\": { \"sandbox\": \"alive\", \"running\": false, \"lastActivityAt\": 1789832474865, \"lastTurnAt\": 1789832490530, \"pendingWakes\": 2, \"nextWakeAt\": 1790002800000 } }\n```\n\n`running` is derived: a turn that has started, has not finished and has shown activity in the last 20 minutes. It covers the whole account, so a turn started from chat, Slack, a webhook, a workflow run or a scheduled wake counts, not just this token's messages. `lastTurnAt` is when the most recent of those turns finished. A `dead` or `paused` sandbox is normal between turns; the next message or wake starts one. `pendingWakes` counts wakes scheduled for the future, up to 100, including each workflow's next run and the daily work session, so a steady count is normal. `nextWakeAt` is the earliest; one well in the past means wakes are not firing.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/agent-status" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "results:read", "responses": { "200": { "description": "``json { \"status\": { \"sandbox\": \"alive\", \"running\": false, \"lastActivityAt\": 1789832474865, \"lastTurnAt\": 1789832490530, \"pendingWakes\": 2, \"nextWakeAt\": 1790002800000 } } ` running is derived: a turn that has started, has not finished and has shown activity in the last 20 minutes. It covers the who", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "object", "properties": { "lastActivityAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastTurnAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "nextWakeAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pendingWakes": { "type": "number" }, "running": { "type": "boolean" }, "sandbox": { "type": "string" } }, "required": [ "lastActivityAt", "lastTurnAt", "nextWakeAt", "pendingWakes", "running", "sandbox" ] } }, "required": [ "status" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/results": { "get": { "operationId": "results", "summary": "Get results", "description": "The growth scoreboard for a window ending now: per-channel sections for email, outbound, LinkedIn, SEO, AI answers and ads, each available with data or unavailable with a reason.\n\nRequires the `results:read` scope.\n\n**Response.** ```json\n{\n \"results\": {\n \"window\": { \"from\": 1789000000000, \"to\": 1789604800000 },\n \"baseline\": { \"from\": 1788395200000, \"to\": 1789000000000 },\n \"harness\": { \"available\": true, \"data\": { } },\n \"email\": {\n \"available\": true,\n \"data\": {\n \"sent\": 120,\n \"sentBaseline\": 96,\n \"draftsAwaiting\": 4,\n \"tracking\": { \"available\": false, \"reason\": \"tracking_off\" },\n \"replies\": {\n \"available\": true,\n \"data\": {\n \"replies\": 7,\n \"bounces\": 2,\n \"repliedContacts\": [{ \"who\": \"Jo Park\", \"company\": \"Northwind\", \"agoDays\": 1, \"intent\": \"interested\" }]\n }\n }\n }\n },\n \"outbound\": { \"available\": true, \"data\": { \"routes\": [ ] } },\n \"linkedin\": {\n \"available\": true,\n \"data\": {\n \"invites\": 14,\n \"health\": { \"needsReauth\": false, \"pausedUntil\": null, \"pauseReason\": null, \"inviteHeadroom\": 6 },\n \"replies\": { \"available\": true, \"data\": { \"count\": 3 } }\n }\n },\n \"seo\": {\n \"available\": true,\n \"data\": { \"postsPublished\": 2, \"postsHeld\": 1, \"postsFailed\": 0, \"views\": 340 }\n },\n \"aeo\": { \"available\": true, \"data\": { } },\n \"ads\": { \"available\": false, \"reason\": \"no_campaigns\" }\n }\n}\n```\n\nThe numbers above are an example of the shape, not real figures, and some fields are left out to keep it short. The tables below list every field. `baseline` is the equal-length window just before `window`, for comparisons such as `sent` against `sentBaseline`.\n\nEach channel section is `{ \"available\": true, \"data\": {…} }`, optionally with `caveats`, or `{ \"available\": false, \"reason\": \"…\" }`. Zero and unknown are different numbers.\n\n### Email\n\n| Field | Meaning |\n|---|---|\n| `sent` | Emails sent in the window |\n| `sentBaseline` | Emails sent in the baseline window |\n| `draftsAwaiting` | Email drafts waiting in the review queue |\n| `tracking` | Opens and clicks, a section of its own: unavailable with `tracking_off` when no tracking domain is set up or tracking is turned off |\n| `replies.data.replies` | People who replied in the window, counted by when the reply arrived. Automatic replies are left out. |\n| `replies.data.bounces` | Emails that bounced in the window |\n| `replies.data.repliedContacts` | The newest five replies: `who`, `company`, `agoDays`, and `intent` when Revnu has read the reply |\n| `replies.data.byIntent` | Replies grouped by intent, when at least one has been classified |\n\nReply rate is not a field: divide `replies` by `sent`. For everyone who replied, list [`GET /leads?status=replied`](/docs/leads).\n\n### LinkedIn\n\nThe LinkedIn section reads the workspace owner's connected LinkedIn account. Counts are for the window unless the table says otherwise.\n\n| Field | Meaning |\n|---|---|\n| `invites` | Connection requests sent in the window. Requests LinkedIn turned away because you were already connected or already invited are left out. |\n| `alreadyConnectedHits` | Requests that hit that already-connected or already-invited wall |\n| `newDMs` | Messages that started a new conversation |\n| `chatReplies` | Messages sent into a conversation that already existed |\n| `inmails` | InMails sent |\n| `baseline` | `{ invites, dms, inmails }` for the baseline window, where `dms` is `newDMs` plus `chatReplies` |\n| `health.needsReauth` | `true` when the LinkedIn connection has expired. Reconnect it in the dashboard. |\n| `health.pausedUntil` | Epoch milliseconds when Revnu's LinkedIn pause ends, or `null` when it isn't paused. Live state, not windowed. |\n| `health.pauseReason` | A short plain-text reason for the pause, such as a rate limit or several provider errors in a row, or `null` |\n| `health.inviteHeadroom` | Connection requests Revnu can still send today: the smaller of what is left of today's limit and this week's |\n| `replies.data.count` | Conversations that got a reply in the window, counted by when the reply arrived |\n| `accepts.data.count` | Connection requests accepted in the window, counted by when Revnu saw the connection |\n| `scoreboard` | All-time requests and acceptances by list, `{ label, invites, maturedInvites, accepts }` each. `maturedInvites` counts requests at least 7 days old plus accepted ones, a fair base for an acceptance rate. |\n\nWhy LinkedIn pauses and when it resumes is in [Why Did LinkedIn Sending Stop?](/docs/linkedin-paused). For one person's connection and conversation, use [`GET /linkedin/person`](/docs/linkedin-person).\n\n### SEO\n\nThe SEO section is about the blog Revnu writes for. `postsPublished` and `postsHeld` count only posts Revnu wrote, not ones you added yourself.\n\n| Field | Meaning |\n|---|---|\n| `postsPublished` | Posts Revnu wrote that were published or exported in the window |\n| `postsHeld` | Posts waiting for your review right now. Live, not windowed. |\n| `postsFailed` | Posts started in the window that failed. A count only: the cause isn't returned. |\n| `refreshes` | `{ applied, skipped }`: updates to live posts Revnu applied or skipped in the window |\n| `views` | Views of your blog posts in the window. `viewsPrev` is the baseline window. |\n| `genCostCents` | Revnu's estimated cost of writing the posts it finished in the window, in cents |\n| `gsc` | Search Console clicks and impressions, a section of its own: `{ clicks, impressions, prevClicks, from, through, ourPosts }`. Unavailable with `not_connected`, `needs_reauth` or `no_data_yet`. |\n| `gsc.data.ourPosts` | The same numbers for your blog pages only, with the top five pages in `top`. `null` until Revnu has page-level data. |\n| `scoreboard` | The last 14 days by content type, plus up to five pages with impressions and no clicks |\n\nSearch Console reports a day or two late, so `gsc` covers a window shifted back by two days. `from` and `through` give the exact dates. `prevClicks` is `null`, not 0, when the data doesn't reach back that far.\n\n### Outbound\n\nOutbound is all-time, not windowed: one row per campaign in `routes`, sorted by sends. Each row has `route`, `delivered`, `replied`, `bounced` and `pending` (leads found but not yet sent), plus `ready` and `drafted` when Revnu could count them, and `sequence` with the campaign's approval state.\n\n### Why a section is unavailable\n\n| Reason | Meaning |\n|---|---|\n| `not_connected` | The channel isn't connected |\n| `needs_reauth` | It was connected, but the connection has expired; reconnect it in the dashboard |\n| `tracking_off` | Open and click tracking isn't set up or is turned off |\n| `no_blog` | Revnu hasn't written for your blog yet |\n| `no_campaigns` | No ad campaigns exist |\n| `not_tracked` | AI-answer visibility hasn't been measured yet |\n| `measurement_stalled` | AI-answer measurements exist but none are recent enough to use |\n| `no_data_yet` | Connected, but nothing has arrived for this window yet |\n| `no_writer_yet` | Revnu doesn't measure this number yet |\n| `read_failed` | This section couldn't be read this time; the others still rendered. Retry. |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/results" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "results:read", "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Start of the window, epoch milliseconds, clamped to between 31 days and one hour ago. Default 24 hours ago.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{ results }", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "$ref": "#/components/schemas/ResultsWindowResult" } }, "required": [ "results" ] } } } }, "400": { "description": "since is not epoch milliseconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked or unknown token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "setup_pending: the account hasn't started its trial", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks results:read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Over the read limit; wait Retry-After seconds", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/workflows": { "get": { "operationId": "workflows", "summary": "List workflows", "description": "The account's recurring workflows with their schedule, next run and step list.\n\nRequires the `results:read` scope.\n\n**Response.** `{ \"workflows\": [{ workflowId, name, description, status, scheduleText, scheduleEcho, scheduleError, deliverTo, nextRunAt, version, steps: [{ id, title, details, gate? }], url }, …] }`.\n\n`status` is `live` or `paused`. `scheduleEcho` is how Revnu understood `scheduleText`, and `scheduleError` is set when it couldn't. `url` opens the workflow in the dashboard, where it can also be edited in chat. Reading needs only `results:read`; changing, running or deleting one needs `workflows:write`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflows" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "results:read", "responses": { "200": { "description": "{ \"workflows\": [{ workflowId, name, description, status, scheduleText, scheduleEcho, scheduleError, deliverTo, nextRunAt, version, steps: [{ id, title, details, gate? }], url }, …] }. status is live or paused. scheduleEcho is how Revnu understood scheduleText, and scheduleError is set when it couldn", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "type": "object", "properties": { "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleEcho": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleText": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "paused", "proposed" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "details": { "type": "array", "items": { "type": "string" } }, "gate": { "type": "object", "properties": { "label": { "type": "string" }, "on": { "type": "boolean" } }, "required": [ "on" ] }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "details", "id", "title" ] } }, "url": { "type": "string" }, "version": { "type": "number" }, "workflowId": { "type": "string" } }, "required": [ "deliverTo", "description", "name", "nextRunAt", "requestedBy", "scheduleEcho", "scheduleError", "scheduleText", "status", "steps", "url", "version", "workflowId" ] } } }, "required": [ "workflows" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "workflowCreate", "summary": "Create a workflow", "description": "Compose a recurring workflow from a schedule in plain words and a list of steps.\n\nRequires the `workflows:write` scope.\n\n**Response.** `{ \"workflow\": { workflowId, status, version, scheduleText, scheduleEcho, scheduleError, nextRunAt, steps, url, … } }`, status `201`. The workflow is live. The schedule resolves after the write: read it back for `scheduleEcho` and `nextRunAt`, or `scheduleError` when the words could not be understood.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-create" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "requestBody": { "required": true, "description": "`name` (up to 120 characters), `scheduleText` (plain words, up to 200 characters; name a time zone such as `America/New_York`, `ET` or `UTC` to run on that clock, otherwise the account's zone is used, and `scheduleEcho` in the response names the zone it resolved to), `steps` (1 to 25). A step is `{ title, details?, gate?, id? }`: `title` is up to 1000 characters, `details` is up to 8 lines of up to 1000 characters each, and `gate: { on: true, label? }` means the step waits for a human ok before it acts. Optional `description` (240 characters) and `deliverTo`, one of the account's connected destinations. Unknown fields or a broken limit are a `400` whose body names the problem, e.g. `{ \"error\": \"steps[2].details lines are at most 1000 characters\" }`. The whole workflow also has to fit in one run, about 6,500 characters of steps in total; past that the `400` says how far over it is.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "{ \"workflow\": { workflowId, status, version, scheduleText, scheduleEcho, scheduleError, nextRunAt, steps, url, … } }, status 201. The workflow is live. The schedule resolves after the write: read it back for scheduleEcho and nextRunAt, or scheduleError when the words could not be understood.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleEcho": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleText": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "paused", "proposed" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "details": { "type": "array", "items": { "type": "string" } }, "gate": { "type": "object", "properties": { "label": { "type": "string" }, "on": { "type": "boolean" } }, "required": [ "on" ] }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "details", "id", "title" ] } }, "url": { "type": "string" }, "version": { "type": "number" }, "workflowId": { "type": "string" } }, "required": [ "deliverTo", "description", "name", "nextRunAt", "requestedBy", "scheduleEcho", "scheduleError", "scheduleText", "status", "steps", "url", "version", "workflowId" ] } }, "required": [ "workflow" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/workflows/{id}/runs": { "get": { "operationId": "workflowRuns", "summary": "List workflow runs", "description": "List a Revnu workflow's runs through the API, newest first. Inspect run status, per-step outcomes, and counts of leads, contacts and people found by each run.\n\nRequires the `results:read` scope.\n\n**Response.** `{ \"runs\": [run, …] }`, newest first, each with its per-step outcomes. `404` for an unknown or another account's workflow.\n\nA run's `status` is `queued` (started with [`POST /workflows/{id}/runs`](/docs/workflow-run) and not picked up yet), `running`, `done`, `failed` or `abandoned` (it never started or never reported back).\n\nEach run has `found: { leads, contacts, people }`: how many leads and contacts this run created, and how many people it added to a company's research list without saving them as contacts. Counting started on 2026-10-02, so runs before then show zero. List them with [`GET /leads?workflowRunId=`](/docs/leads).", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-runs" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "results:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 50. Default 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "{ \"runs\": [run, …] }, newest first, each with its per-step outcomes. 404 for an unknown or another account's workflow. A run's status is queued (started with POST /workflows/{id}/runs and not picked up yet), running, done, failed or abandoned (it never started or never reported back). Each run has f", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "found": { "type": "object", "properties": { "contacts": { "type": "number" }, "leads": { "type": "number" }, "people": { "type": "number" } }, "required": [ "contacts", "leads", "people" ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "startedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "abandoned", "done", "failed", "queued", "running" ] }, "stepResults": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "gateUnmet": { "type": "boolean" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outcome": { "type": "string" }, "reviewItemId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stepId": { "type": "string" } }, "required": [ "at", "gateUnmet", "note", "outcome", "reviewItemId", "stepId" ] } }, "workflowVersion": { "type": "number" } }, "required": [ "error", "finishedAt", "found", "headline", "id", "startedAt", "status", "stepResults", "workflowVersion" ] } } }, "required": [ "runs" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "workflowRun", "summary": "Run a workflow now", "description": "Start a workflow's next run within about a minute, without changing its schedule.\n\nRequires the `workflows:write` scope.\n\n**Response.** `202 { \"run\": { id, status: \"queued\", startedAt }, \"deduplicated\": false }`. The run starts within about a minute and then shows in [`GET /workflows/{id}/runs`](/docs/workflow-runs) under the same `id`, moving from `queued` to `running` and then `done` or `failed`.\n\n`deduplicated: true` means no new run was queued: the `clientRequestId` was seen before, or the workflow already has a run queued or running, and `run` is that one.\n\n| Code | Meaning |\n|---|---|\n| 409 | `error` is `paused` (resume it first), `schedule_pending` (the schedule is still being set up, so retry shortly) or `schedule_error` (fix `scheduleText`). |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-run" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "`{ clientRequestId? }`. Both the body and the field are optional. `clientRequestId` (1 to 128 characters of `A-Z a-z 0-9 _ . : -`) makes the call safe to retry: the same id on the same workflow returns the same run.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "202": { "description": "202 { \"run\": { id, status: \"queued\", startedAt }, \"deduplicated\": false }. The run starts within about a minute and then shows in GET /workflows/{id}/runs under the same id, moving from queued to running and then done or failed. deduplicated: true means no new run was queued: the clientRequestId was", "content": { "application/json": { "schema": { "type": "object", "properties": { "deduplicated": { "type": "boolean" }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": "number" }, "status": { "type": "string", "enum": [ "abandoned", "done", "failed", "queued", "running" ] } }, "required": [ "id", "startedAt", "status" ] } }, "required": [ "deduplicated", "run" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "error is paused (resume it first), schedule_pending (the schedule is still being set up, so retry shortly) or schedule_error (fix scheduleText).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/workflows/{id}": { "patch": { "operationId": "workflowUpdate", "summary": "Update a workflow", "description": "Change a workflow's name, schedule, steps, destination or status. Steps are replaced whole.\n\nRequires the `workflows:write` scope.\n\n**Response.** `{ \"workflow\": { … } }`, the updated workflow with its new `version`. `404` for an unknown or another account's workflow. `409` when `deliverTo` is not a connected destination; the message lists the options.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-update" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Any of `name`, `description`, `scheduleText`, `steps`, `deliverTo`, `status` (`\"live\"` or `\"paused\"`), with the same limits as create. `steps` replaces the whole list, so send back the steps you are not changing and keep their `id` so run history stays attached. A changed `scheduleText` is re-resolved after the write.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"workflow\": { … } }, the updated workflow with its new version. 404 for an unknown or another account's workflow. 409 when deliverTo is not a connected destination; the message lists the options.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleEcho": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleText": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "paused", "proposed" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "details": { "type": "array", "items": { "type": "string" } }, "gate": { "type": "object", "properties": { "label": { "type": "string" }, "on": { "type": "boolean" } }, "required": [ "on" ] }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "details", "id", "title" ] } }, "url": { "type": "string" }, "version": { "type": "number" }, "workflowId": { "type": "string" } }, "required": [ "deliverTo", "description", "name", "nextRunAt", "requestedBy", "scheduleEcho", "scheduleError", "scheduleText", "status", "steps", "url", "version", "workflowId" ] } }, "required": [ "workflow" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "delete": { "operationId": "workflowDelete", "summary": "Delete a workflow", "description": "Remove a workflow. Nothing fires again, and it drops out of every read.\n\nRequires the `workflows:write` scope.\n\n**Response.** `{ \"ok\": true, \"name\": \"…\" }`. The workflow disappears from `GET /workflows`, its pending wake is cancelled, and `GET /workflows/{id}/runs` answers `404` from then on. `404` for an unknown or another account's workflow.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-delete" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"ok\": true, \"name\": \"…\" }. The workflow disappears from GET /workflows, its pending wake is cancelled, and GET /workflows/{id}/runs answers 404 from then on. 404 for an unknown or another account's workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "name", "ok" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/workflows/{id}/pause": { "post": { "operationId": "workflowPause", "summary": "Pause a workflow", "description": "Pause a Revnu workflow through the API without losing its steps or run history. Cancel its pending wake and keep it paused until you explicitly resume it.\n\nRequires the `workflows:write` scope.\n\n**Response.** `{ \"workflow\": { …, status: \"paused\" } }`. The pending wake is cancelled; nothing fires until it is resumed. Idempotent. `404` for an unknown or another account's workflow.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-pause" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"workflow\": { …, status: \"paused\" } }. The pending wake is cancelled; nothing fires until it is resumed. Idempotent. 404 for an unknown or another account's workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleEcho": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleText": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "paused", "proposed" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "details": { "type": "array", "items": { "type": "string" } }, "gate": { "type": "object", "properties": { "label": { "type": "string" }, "on": { "type": "boolean" } }, "required": [ "on" ] }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "details", "id", "title" ] } }, "url": { "type": "string" }, "version": { "type": "number" }, "workflowId": { "type": "string" } }, "required": [ "deliverTo", "description", "name", "nextRunAt", "requestedBy", "scheduleEcho", "scheduleError", "scheduleText", "status", "steps", "url", "version", "workflowId" ] } }, "required": [ "workflow" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/workflows/{id}/resume": { "post": { "operationId": "workflowResume", "summary": "Resume a workflow", "description": "Set a paused workflow live again; the next run is scheduled from its cadence.\n\nRequires the `workflows:write` scope.\n\n**Response.** `{ \"workflow\": { …, status: \"live\", nextRunAt } }`. Idempotent. Resuming a workflow the agent proposed accepts it. `404` for an unknown or another account's workflow.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/workflow-resume" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "workflows:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"workflow\": { …, status: \"live\", nextRunAt } }. Idempotent. Resuming a workflow the agent proposed accepts it. 404 for an unknown or another account's workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string" }, "name": { "type": "string" }, "nextRunAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requestedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleEcho": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleText": { "type": "string" }, "status": { "type": "string", "enum": [ "live", "paused", "proposed" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "details": { "type": "array", "items": { "type": "string" } }, "gate": { "type": "object", "properties": { "label": { "type": "string" }, "on": { "type": "boolean" } }, "required": [ "on" ] }, "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "details", "id", "title" ] } }, "url": { "type": "string" }, "version": { "type": "number" }, "workflowId": { "type": "string" } }, "required": [ "deliverTo", "description", "name", "nextRunAt", "requestedBy", "scheduleEcho", "scheduleError", "scheduleText", "status", "steps", "url", "version", "workflowId" ] } }, "required": [ "workflow" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/leads": { "get": { "operationId": "leads", "summary": "List leads", "description": "Leads newest first with status, score, primary contact and your own columns, paged by an opaque cursor. Draft bodies are only on GET /leads/{id}.\n\nRequires the `leads:read` scope.\n\n**Response.** `{ \"leads\": [lead, …], \"nextCursor\": \"…\" | null }`. A page is bounded in rows and in bytes, and holds at most 30 leads that are in a LinkedIn sequence, so pass `nextCursor` back until it is null.\n\nA lead is `{ id, domain, companyName, status, replyKind, declineReason, score, scoreReasons, vertical, archetype, tags, fields, contact, linkedin, createdAt, workflowRunId }`, plus `runContactIds`, `runPeople` and `runCreatedLead` when you pass `workflowRunId`. `workflowRunId` is the workflow run that created the lead, or `null`. `fields` is your account's configured lead columns, exactly the dashboard table, as `[{ key, value }]` entries with each value cut at 1,000 characters, for example `[{ \"key\": \"account_case\", \"value\": \"…\" }, { \"key\": \"slack_thread\", \"value\": \"1790064680.268899\" }]`. The list never carries the draft or the research behind a value; read `GET /leads/{id}` for those.\n\n| Code | Meaning |\n|---|---|\n| 404 | `workflowRunId` is not one of your workflow runs. |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/leads" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by lead status: qualified, drafted, sent, partially_sent, replied, declined or bounced. Anything else is a 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1 to 100. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The nextCursor from the previous page.", "schema": { "type": "string" } }, { "name": "workflowRunId", "in": "query", "required": false, "description": "Only the leads this workflow run created or returned people on (a run id from GET /workflows/{id}/runs). Each lead then also has runContactIds, the contacts this run created, runPeople, the people this run returned on the company's research list without saving them as contacts ({ name, title, email, linkedinUrl, profileUrl, photoUrl, role, alreadyKnown }; role is economic for the buyer, champion, technical, user or null, and alreadyKnown is true when the company had the person before this run), and runCreatedLead, true when the run created the lead itself.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"leads\": [lead, …], \"nextCursor\": \"…\" | null }. A page is bounded in rows and in bytes, and holds at most 30 leads that are in a LinkedIn sequence, so pass nextCursor back until it is null. A lead is { id, domain, companyName, status, replyKind, declineReason, score, scoreReasons, vertical, archet", "content": { "application/json": { "schema": { "type": "object", "properties": { "leads": { "type": "array", "items": { "type": "object", "properties": { "archetype": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "photoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "emailStatus", "firstName", "linkedinUrl", "name", "photoUrl", "title" ] }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "declineReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "id": { "type": "string" }, "linkedin": { "anyOf": [ { "type": "object", "properties": { "acceptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "invitedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastMessageAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "dueAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "email", "linkedin_invite", "linkedin_message" ] } }, "required": [ "dueAt", "kind" ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repliedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "seenAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sequence": { "type": "string" }, "status": { "type": "string", "enum": [ "cannot_start", "checking", "connected", "finished", "invite_sent", "messaged", "not_started", "replied", "seen", "stopped" ] } }, "required": [ "acceptedAt", "invitedAt", "lastMessageAt", "nextStep", "reason", "repliedAt", "seenAt", "sequence", "status" ] }, { "type": "null" } ] }, "replyKind": { "type": [ "string", "null" ], "enum": [ "automatic", "human", null ] }, "runContactIds": { "type": "array", "items": { "type": "string" } }, "runCreatedLead": { "type": "boolean" }, "runPeople": { "type": "array", "items": { "type": "object", "properties": { "alreadyKnown": { "type": "boolean" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "photoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "profileUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": [ "string", "null" ], "enum": [ "champion", "economic", "technical", "user", null ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "alreadyKnown", "email", "linkedinUrl", "name", "photoUrl", "profileUrl", "role", "title" ] } }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "scoreReasons": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "bounced", "declined", "drafted", "partially_sent", "qualified", "replied", "sent" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "archetype", "companyName", "contact", "createdAt", "declineReason", "domain", "fields", "id", "linkedin", "replyKind", "score", "scoreReasons", "status", "tags", "vertical", "workflowRunId" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "leads", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "workflowRunId is not one of your workflow runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/leads/{id}": { "get": { "operationId": "lead", "summary": "Get a lead", "description": "One lead with its contacts, the surfaced draft, and the research behind each column.\n\nRequires the `leads:read` scope.\n\n**Response.** `{ \"lead\": { …, fields, draft, research, contacts: [contact, …], contactsTruncated: false } }`. Contacts are capped at 50, with `contactsTruncated: true` when there were more. `linkedin` is where the lead stands in a sequence with LinkedIn steps, or `null`, as described in [LinkedIn sequence progress](/docs/leads#linkedin-sequence-progress). The lead and each contact carry `workflowRunId`, the workflow run that created it, or `null`. `404` for an unknown or another account's lead.\n\nA contact is `{ id, workflowRunId, email, name, firstName, title, linkedinUrl, photoUrl, emailStatus, role, isPrimary, identityConfidence }`, with `null` for anything not known.\n\n`draft` is the surfaced draft, `{ subject, body }` (each cut at 16,000 characters), or `null` when there is none. `research` is a list of entries, one per key the agent saved research under: `{ key, reasoning, sources: [{ url, title }], sourcesTruncated }`, the agent's reasoning (cut at 8,000 characters) and up to 20 sources behind that value. A source whose URL is longer than 2,048 characters is left out rather than cut, and `sourcesTruncated` says when anything was left out. Keys with no visible column appear here too.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/lead" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"lead\": { …, fields, draft, research, contacts: [contact, …], contactsTruncated: false } }. Contacts are capped at 50, with contactsTruncated: true when there were more. linkedin is where the lead stands in a sequence with LinkedIn steps, or null, as described in LinkedIn sequence progress. The le", "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "type": "object", "properties": { "archetype": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "photoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "email", "emailStatus", "firstName", "linkedinUrl", "name", "photoUrl", "title" ] }, { "type": "null" } ] }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "emailStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "identityConfidence": { "type": [ "string", "null" ], "enum": [ "confirmed", "possible", null ] }, "isPrimary": { "type": "boolean" }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "photoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": [ "string", "null" ], "enum": [ "champion", "economic", "technical", "user", null ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "emailStatus", "firstName", "id", "identityConfidence", "isPrimary", "linkedinUrl", "name", "photoUrl", "role", "title", "workflowRunId" ] } }, "contactsTruncated": { "type": "boolean" }, "createdAt": { "type": "number" }, "declineReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "type": "string" }, "draft": { "anyOf": [ { "type": "object", "properties": { "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "body", "subject" ] }, { "type": "null" } ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "id": { "type": "string" }, "linkedin": { "anyOf": [ { "type": "object", "properties": { "acceptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "invitedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastMessageAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "nextStep": { "anyOf": [ { "type": "object", "properties": { "dueAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "email", "linkedin_invite", "linkedin_message" ] } }, "required": [ "dueAt", "kind" ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repliedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "seenAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sequence": { "type": "string" }, "status": { "type": "string", "enum": [ "cannot_start", "checking", "connected", "finished", "invite_sent", "messaged", "not_started", "replied", "seen", "stopped" ] } }, "required": [ "acceptedAt", "invitedAt", "lastMessageAt", "nextStep", "reason", "repliedAt", "seenAt", "sequence", "status" ] }, { "type": "null" } ] }, "replyKind": { "type": [ "string", "null" ], "enum": [ "automatic", "human", null ] }, "research": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "reasoning": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } }, "required": [ "title", "url" ] } }, "sourcesTruncated": { "type": "boolean" } }, "required": [ "key", "reasoning", "sources", "sourcesTruncated" ] } }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "scoreReasons": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "bounced", "declined", "drafted", "partially_sent", "qualified", "replied", "sent" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "workflowRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "archetype", "companyName", "contact", "contacts", "contactsTruncated", "createdAt", "declineReason", "domain", "draft", "fields", "id", "linkedin", "replyKind", "research", "score", "scoreReasons", "status", "tags", "vertical", "workflowRunId" ] } }, "required": [ "lead" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "patch": { "operationId": "leadUpdate", "summary": "Update a lead's labels", "description": "Set vertical, archetype and tags on a lead. The only write on leads: the API can't create leads or change status, drafts or contacts.\n\nRequires the `leads:write` scope.\n\n**Response.** `{ \"lead\": { id, domain, vertical, archetype, tags } }`, the labels as stored. The response carries nothing a `leads:read` token would show; read the lead back for the rest. Status, drafts, contacts and research stay read-only; the agent and the dashboard own them. `404` for an unknown or another account's lead.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/lead-update" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Any of `vertical`, `archetype` (strings, at most 120 characters) and `tags` (up to 20 strings of at most 64 characters, deduplicated, order kept). `null` clears a field. Unknown fields are a `400`, so a typo never silently does nothing.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"lead\": { id, domain, vertical, archetype, tags } }, the labels as stored. The response carries nothing a leads:read token would show; read the lead back for the rest. Status, drafts, contacts and research stay read-only; the agent and the dashboard own them. 404 for an unknown or another account'", "content": { "application/json": { "schema": { "type": "object", "properties": { "lead": { "type": "object", "properties": { "archetype": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "type": "string" }, "id": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "vertical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "archetype", "domain", "id", "tags", "vertical" ] } }, "required": [ "lead" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/blocklist": { "get": { "operationId": "blocklist", "summary": "List the block list", "description": "The do-not-contact entries the send and research gates enforce, newest first.\n\nRequires the `leads:read` scope.\n\n**Response.** `{ \"entries\": [entry, …], \"nextCursor\": \"…\" | null }`. An entry is `{ id, kind, value, reason, source, addedBy, addedAt }`. `kind` is `domain`, `email` or `linkedin`; a `linkedin` value is the profile URL in the form `https://www.linkedin.com/in/`; `source` says who added it: `customer_import`, `customer` (dashboard), `agent`, `opt_out_reply` (a provider-reported unsubscribe) or `api`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/blocklist" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Rows per page, 1 to 200. Default 50.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The nextCursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"entries\": [entry, …], \"nextCursor\": \"…\" | null }. An entry is { id, kind, value, reason, source, addedBy, addedAt }. kind is domain, email or linkedin; a linkedin value is the profile URL in the form https://www.linkedin.com/in/; source says who added it: customer_import, customer (dashboar", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "addedAt": { "type": "number" }, "addedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "domain", "email", "linkedin" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "agent", "api", "customer", "customer_import", "customer_sync", "opt_out_reply" ] }, "value": { "type": "string" } }, "required": [ "addedAt", "addedBy", "id", "kind", "reason", "source", "value" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "entries", "nextCursor" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "blocklistAdd", "summary": "Add block list entries", "description": "Block companies, mailboxes or LinkedIn profiles from outreach. Idempotent, up to 500 per call.\n\nRequires the `leads:write` scope.\n\n**Response.** `{ \"added\": 3, \"existing\": 0, \"invalid\": [] }`. `existing` counts values already on the list, so re-sending a whole list is safe. `invalid` lists the strings that could not be read as a domain, an email or a LinkedIn profile, trimmed and cut to 200 characters, blanks dropped; nothing else in the call is affected by them. Entries carry `source: \"api\"` and the token's label.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/blocklist-add" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:write", "requestBody": { "required": true, "description": "`values`, 1 to 500 raw strings of up to 320 characters each: bare domains, emails, `mailto:` links, `Name ` forms or LinkedIn profile links (`linkedin.com/in/`, with or without `https://www.`), all normalised. Any other LinkedIn link, such as a company page, is invalid. `reason` is an optional note of up to 500 characters stored on every entry in the call.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"added\": 3, \"existing\": 0, \"invalid\": [] }. existing counts values already on the list, so re-sending a whole list is safe. invalid lists the strings that could not be read as a domain, an email or a LinkedIn profile, trimmed and cut to 200 characters, blanks dropped; nothing else in the call is a", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "number" }, "existing": { "type": "number" }, "invalid": { "type": "array", "items": { "type": "string" } } }, "required": [ "added", "existing", "invalid" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/blocklist/{id}": { "delete": { "operationId": "blocklistRemove", "summary": "Remove a block list entry", "description": "Unblock one company, mailbox or LinkedIn profile by the id the list returns. Revnu may then contact them again. Unsubscribes can't be removed.\n\nRequires the `leads:write` scope.\n\n**Response.** `{ \"removed\": entry }`. `404` for an unknown or another account's id. `409` for an address that unsubscribed (`source: opt_out_reply`): it stays blocked. Customer-sync exclusions also return `409` with `customer_relationship`; deleting a block does not remove a customer relationship.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/blocklist-remove" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"removed\": entry }. 404 for an unknown or another account's id. 409 for an address that unsubscribed (source: opt_out_reply): it stays blocked. Customer-sync exclusions also return 409 with customer_relationship; deleting a block does not remove a customer relationship.", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "object", "properties": { "addedAt": { "type": "number" }, "addedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "domain", "email", "linkedin" ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "agent", "api", "customer", "customer_import", "customer_sync", "opt_out_reply" ] }, "value": { "type": "string" } }, "required": [ "addedAt", "addedBy", "id", "kind", "reason", "source", "value" ] } }, "required": [ "removed" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/linkedin/person": { "get": { "operationId": "linkedinPerson", "summary": "Look up a LinkedIn person", "description": "One person's LinkedIn relationship with each connected account, read live from LinkedIn: connected or not, any pending invite and when it was sent, and the conversation.\n\nRequires the `leads:read` scope.\n\n**Response.** `{ \"person\": { providerId, publicIdentifier, name, headline } | null, \"accounts\": [account, …] }`, one entry per connected LinkedIn account.\n\nAn account read in full is `{ account, connectedAs, state: \"ok\", connected, invite, revnuInvite, messages, messagesTruncated, lastReplyAt }`:\n\n- `connected` is `true` when this account and the person are first-degree connections.\n- `invite` is the request LinkedIn reports between them, or `null`: `{ direction: \"sent\" | \"received\" | null, status: \"pending\" | \"ignored\" | \"withdrawn\", at }`, where `at` is when it was sent (epoch milliseconds) if LinkedIn says.\n- `revnuInvite` is Revnu's own record when Revnu sent the invite from this account: `{ sentAt, acceptedAt, withdrawnAt }`. `acceptedAt` is when Revnu first saw the person connected, not LinkedIn's exact time.\n- `messages` are the newest 50 in the conversation, oldest first: `{ at, from: \"you\" | \"them\", sentBy, kind, text }`. `sentBy` is `\"agent\"` when Revnu sent it, `\"person\"` when someone replied from Revnu's inbox, and `null` when it was typed in LinkedIn. `messagesTruncated` says older messages exist.\n- `lastReplyAt` is the time of their newest message, or `null`.\n\nAn account that could not be read has a `state` instead: `not_connected`, `needs_reauth` (reconnect it in the dashboard), `paced` with `message` and `retryAt` (the account's daily profile-lookup budget is spent), or `error` with `message`, including when no profile matches.\n\n| Code | Meaning |\n|---|---|\n| 400 | `profile` is missing or is not a LinkedIn profile URL or id. |\n| 404 | No connected LinkedIn account has the name in `account`. |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/linkedin-person" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:read", "parameters": [ { "name": "profile", "in": "query", "required": true, "description": "Required. A linkedin.com/in/ URL, a public id such as tom-park, or a member id (ACoAA…).", "schema": { "type": "string" } }, { "name": "account", "in": "query", "required": false, "description": "The name of one connected LinkedIn account in your workspace. Without it, every connected account is checked.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"person\": { providerId, publicIdentifier, name, headline } | null, \"accounts\": [account, …] }, one entry per connected LinkedIn account. An account read in full is { account, connectedAs, state: \"ok\", connected, invite, revnuInvite, messages, messagesTruncated, lastReplyAt }: - connected is true w", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPersonAccount" } }, "person": { "anyOf": [ { "type": "object", "properties": { "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publicIdentifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "headline", "name", "providerId", "publicIdentifier" ] }, { "type": "null" } ] } }, "required": [ "accounts", "person" ] } } } }, "400": { "description": "profile is missing or is not a LinkedIn profile URL or id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No connected LinkedIn account has the name in account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/customers": { "post": { "operationId": "customerSync", "summary": "Sync existing customers", "description": "Import signups, trials and customers into Leads and exclude them from cold outreach.\n\nRequires the `leads:write` scope.\n\n**Response.** `{ \"ok\": true, \"leads\": 1, \"stage\": \"customer\" }`. A stale `sourceUpdatedAt` returns `ignored: true` and the retained relationship stage.\n\n`leads` counts matched or created company records. A personal email or LinkedIn profile can return zero company records while still being excluded. Repeat the same `source` and `externalId` to update the relationship without duplicating the company. Outreach history is preserved. If several customer records match a company, a paying customer takes precedence over a trial, signup or former customer.\n\nKnown emails, company domains and LinkedIn profiles enter the enforced cold-outreach exclusions. Queued emails and open cold-outreach approval cards attached to matched leads or contacts are cancelled. Send gates recheck exclusions before sending; delivered messages cannot be recalled. Known contact profiles saved later are added to the exclusions too. An email alone cannot identify an unknown LinkedIn recipient.\n\nCancellation uses `former_customer` and keeps the exclusion. Omitting a customer from a later import does not unblock them. Customer-sync blocks cannot be removed through the blocklist endpoint.\n\nA `400` identifies an invalid payload. A `401` means the token is missing or invalid; `403` means it lacks `leads:write`. Keep tokens server-side, verify signatures on your source provider's webhook handler, and retry network failures or `5xx` responses with backoff. Read the current source record and serialize updates per customer ID so a delayed event cannot overwrite newer state. Check a synced identifier through [the block list](/docs/blocklist). Confirm a real source change appears there before treating ongoing sync as connected.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/customer-sync" }, "security": [ { "personalToken": [] } ], "x-revnu-scope": "leads:write", "requestBody": { "required": true, "description": "Send one customer record per request. Required fields:\n\n| Field | Value |\n| --- | --- |\n| `source` | Stable source label, 1–80 letters, digits, underscores or hyphens. |\n| `externalId` | Stable record ID within that source, up to 200 characters. |\n| `stage` | `signed_up`, `trial`, `customer` or `former_customer`. |\n\nSupply at least one identifying field: `email`, `website`, `domains` or `linkedinUrls`. `domains` and `linkedinUrls` take at most 20 values each. Company domains exclude everyone at that company; personal providers such as gmail.com are rejected as company domains. An email at a personal provider excludes that address only. LinkedIn values must be personal profile URLs, not company pages.\n\nOptional `name` and `companyName` describe the customer. Optional `signedUpAt` is a Unix timestamp in milliseconds. Supply `sourceUpdatedAt` with the source snapshot timestamp in milliseconds to prevent delayed imports or retries replacing newer relationship data. Keep using it on subsequent updates for the same source record. Text fields are limited to 320 characters, except for the source and ID limits above. Unknown fields are rejected. The API token determines the account; never include a creator ID.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"ok\": true, \"leads\": 1, \"stage\": \"customer\" }. A stale sourceUpdatedAt returns ignored: true and the retained relationship stage. leads counts matched or created company records. A personal email or LinkedIn profile can return zero company records while still being excluded. Repeat the same source", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "ignored": { "type": "boolean" }, "leads": { "type": "number" }, "ok": { "type": "boolean", "const": true }, "stage": { "type": "string", "enum": [ "customer", "former_customer", "signed_up", "trial" ] } }, "required": [ "ignored", "leads", "ok", "stage" ] }, { "type": "object", "properties": { "leads": { "type": "number" }, "ok": { "type": "boolean", "const": true }, "stage": { "type": "string", "enum": [ "customer", "former_customer", "signed_up", "trial" ] } }, "required": [ "leads", "ok", "stage" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/SetupPending" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/setup": { "get": { "operationId": "setupStatus", "summary": "Get setup status", "description": "Where a new account is in setup (website, researching, review, payment, start or done) and the exact next step. Works before the account has paid.\n\n**Response.** ```json\n{ \"setup\": { \"stage\": \"review\", \"next\": \"Show the customer what Revnu understood…\", \"account\": { \"name\": \"Acme\", \"website\": \"https://acme.com\" }, \"dashboardUrl\": \"https://revnu.com/dashboard\", \"review\": { \"businessName\": \"Acme\", \"researchFailed\": false, \"rows\": [{ \"id\": \"sells\", \"kind\": \"fact\", \"label\": \"What You Sell\", \"found\": \"Invoicing for agencies\", \"sources\": [\"https://acme.com\"], \"required\": true }] } } }\n```\n\n`stage` is one of `website`, `researching`, `review`, `payment`, `start` and `done`. Every stage carries `next`, the step to take in words. Follow it.\n\n| Stage | Extra fields | Next step |\n|---|---|---|\n| `website` | none | [`POST /setup/website`](/docs/setup-website) |\n| `researching` | `research`: the current `step`, `findings` so far, `startedAt` | Poll again in about 20 seconds |\n| `review` | `review`: `businessName`, `researchFailed`, and `rows` of `{ id, kind, label, question?, found, sources, required }` | Show the customer every row, then [`POST /setup/confirm`](/docs/setup-confirm) |\n| `payment` | `payment`: `priceUsdPerMonth`, `trialDays`, `freeMonths`, `cardAtCheckout`, `status` | [`POST /setup/checkout`](/docs/setup-checkout), then poll until `start` |\n| `start` | `payment`: `status`, `trialEndsAt` | [`POST /setup/finish`](/docs/setup-finish) |\n| `done` | `payment`: `status` | Nothing; Revnu is working |\n\nOffers differ by account, so read `payment` before telling the customer what checkout means: `trialDays` is the free period (0 for none), `freeMonths` covers invite offers with free months, and `cardAtCheckout` says whether Stripe's page asks for a card. An account with a YC deal has no `payment` at the `payment` stage; `next` sends the customer to the dashboard to add a card. When research failed, `review.researchFailed` is `true` and a corrected address can go to [`POST /setup/website`](/docs/setup-website) again.\n\nThe CLI runs this whole flow: `npx @revnu/cli setup --json`. See [Install the CLI](/docs/cli).", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/setup-status" }, "security": [ { "personalToken": [] } ], "responses": { "200": { "description": "``json { \"setup\": { \"stage\": \"review\", \"next\": \"Show the customer what Revnu understood…\", \"account\": { \"name\": \"Acme\", \"website\": \"https://acme.com\" }, \"dashboardUrl\": \"https://revnu.com/dashboard\", \"review\": { \"businessName\": \"Acme\", \"researchFailed\": false, \"rows\": [{ \"id\": \"sells\", \"kind\": \"fact", "content": { "application/json": { "schema": { "type": "object", "properties": { "setup": { "anyOf": [ { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "payment": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "trialEndsAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "status", "trialEndsAt" ] }, { "type": "null" } ] }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "payment", "stage" ] }, { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "payment": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, { "type": "null" } ] }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "payment", "stage" ] }, { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "payment": { "type": "object", "properties": { "cardAtCheckout": { "type": "boolean" }, "freeMonths": { "type": "number" }, "priceUsdPerMonth": { "type": "number" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trialDays": { "type": "number" } }, "required": [ "cardAtCheckout", "freeMonths", "priceUsdPerMonth", "status", "trialDays" ] }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "payment", "stage" ] }, { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "research": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "string" } }, "startedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "step": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "findings", "startedAt", "step" ] }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "research", "stage" ] }, { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "review": { "type": "object", "properties": { "businessName": { "type": "string" }, "researchFailed": { "type": "boolean" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "found": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "fact", "question", "value" ] }, "label": { "type": "string" }, "question": { "type": "string" }, "required": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "found", "id", "kind", "label", "required", "sources" ] } } }, "required": [ "businessName", "researchFailed", "rows" ] }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "review", "stage" ] }, { "type": "object", "properties": { "account": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "website" ] }, "dashboardUrl": { "type": "string" }, "next": { "type": "string" }, "stage": { "$ref": "#/components/schemas/SetupStage" } }, "required": [ "account", "dashboardUrl", "next", "stage" ] } ] } }, "required": [ "setup" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/setup/website": { "post": { "operationId": "setupWebsite", "summary": "Set the business website", "description": "Give a new account its website. Revnu checks the site exists, then researches the business, which takes about a minute.\n\n**Response.** | Code | Meaning |\n|---|---|\n| 200 | `{ \"ok\": true }`. Research has started; poll [setup status](/docs/setup-status) until the stage is `review`. |\n| 400 | `url` missing or too long, a bad `timeZone`, or an unknown field. |\n| 409 | `rejected` with a `message`: the site doesn't exist or isn't answering, it is a social network rather than the business's own site, or the account already has a website. |\n\nAn account that already has a website returns `409`, unless its research failed, in which case a corrected address starts it again. One Revnu login holds one business: a different business needs a different account, signed in with that business's email.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/setup-website" }, "security": [ { "personalToken": [] } ], "requestBody": { "required": true, "description": "| Field | Type | Meaning |\n|---|---|---|\n| `url` | string, required | The business's own website, up to 300 characters. `acme.com` and `https://acme.com` both work. |\n| `timeZone` | string | An IANA name such as `Europe/London`, used for sending windows. |\n\nUnknown fields are a `400`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"ok\": true }. Research has started; poll setup status until the stage is review.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "url missing or too long, a bad timeZone, or an unknown field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "rejected with a message: the site doesn't exist or isn't answering, it is a social network rather than the business's own site, or the account already has a website.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/setup/confirm": { "post": { "operationId": "setupConfirm", "summary": "Confirm the business details", "description": "Save the customer's answers to the setup review. Becomes Revnu's memory of the business, exactly as the dashboard review does.\n\n**Response.** | Code | Meaning |\n|---|---|\n| 200 | `{ \"ok\": true }`. The stage moves to `payment`. |\n| 400 | The body isn't the shape above, or has an unknown field. |\n| 409 | `rejected` with a `message`: a row id that isn't in the review, a required row left empty, no website yet, or setup already finished. |\n\nAfter setup, change what Revnu knows in **Settings → Memory**. With the CLI: `revnu setup confirm --keep-found --row =`.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/setup-confirm" }, "security": [ { "personalToken": [] } ], "requestBody": { "required": true, "description": "| Field | Type | Meaning |\n|---|---|---|\n| `rows` | array, required | Up to 40 `{ id, value }` objects, each value up to 2,000 characters. Ids come from `review.rows`. |\n| `businessName` | string | The corrected business name, up to 120 characters. |\n| `extra` | string | Anything else Revnu should know, up to 4,000 characters. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "{ \"ok\": true }. The stage moves to payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "The body isn't the shape above, or has an unknown field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "rejected with a message: a row id that isn't in the review, a required row left empty, no website yet, or setup already finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/setup/checkout": { "post": { "operationId": "setupCheckout", "summary": "Get a checkout link", "description": "A Stripe Checkout link that starts the customer's subscription, with a free trial when their account has one. The customer finishes it on Stripe's page, where any card is entered.\n\n**Response.** ```json\n{ \"url\": \"https://checkout.stripe.com/c/pay/cs_live_…\" }\n```\n\nGive the link to the customer. They open it and finish on Stripe's page themselves. Stripe's webhook, not this call, starts the subscription; poll [setup status](/docs/setup-status) until the stage is `start`. Stripe Checkout links last 24 hours.\n\nBefore you hand it over, read `payment` from setup status and tell the customer what they are agreeing to: the price, the free period if any, and whether the page asks for a card. Each call makes a new Checkout session, and a new one stops the earlier link working, so ask for a new link only when the customer has lost theirs. The CLI's `revnu setup checkout` reuses the link it handed out.\n\n| Code | Meaning |\n|---|---|\n| 200 | `{ \"url\": \"…\" }` |\n| 409 | `rejected` with a `message`: the review isn't confirmed yet, or the account has a YC deal and adds its card in the dashboard. |", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/setup-checkout" }, "security": [ { "personalToken": [] } ], "responses": { "200": { "description": "{ \"url\": \"…\" }", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "rejected with a message: the review isn't confirmed yet, or the account has a YC deal and adds its card in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/v1/setup/finish": { "post": { "operationId": "setupFinish", "summary": "Start Revnu", "description": "Once the trial is running, start Revnu's first work now rather than waiting for the automatic start 15 minutes after the trial begins.\n\n**Response.** | Code | Meaning |\n|---|---|\n| 200 | `{ \"started\": true, \"requestId\": \"…\" }`, or `{ \"started\": false, \"alreadyStarted\": true }` when Revnu has already started. Safe to call twice. |\n| 409 | `rejected` with a `message`: the subscription doesn't exist yet (the message names the missing step), or the account starts from the dashboard, as YC-deal and Managed accounts do. |\n\nAfter it starts, its first work lands in the [review queue](/docs/review-list). Without a call here, Revnu starts on its own 15 minutes after the trial begins.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/setup-finish" }, "security": [ { "personalToken": [] } ], "responses": { "200": { "description": "{ \"started\": true, \"requestId\": \"…\" }, or { \"started\": false, \"alreadyStarted\": true } when Revnu has already started. Safe to call twice.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "alreadyStarted": { "type": "boolean" }, "started": { "type": "boolean" } }, "required": [ "alreadyStarted", "started" ] }, { "type": "object", "properties": { "requestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "started": { "type": "boolean" } }, "required": [ "requestId", "started" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "rejected with a message: the subscription doesn't exist yet (the message names the missing step), or the account starts from the dashboard, as YC-deal and Managed accounts do.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/content/v1/posts": { "get": { "operationId": "contentPosts", "summary": "List posts", "description": "Every published post, newest first, with cursor paging and filters by content type and time.\n\n**Response.** `{ \"blog\": {…}, \"nav\": […], \"posts\": [summary, …], \"cursor\": \"…\" | null }`. Each summary carries `slug`, `title`, `contentType`, `metaDescription`, `canonicalPath`, `canonicalUrl`, `heroImageUrl`, `readingMinutes`, `publishedAt` and `updatedAt`, which is everything a listing page or a sitemap needs. Keep requesting with the returned `cursor` until it is `null` to get every post.\n\nThe unfiltered list is the source of truth for what exists. A post that disappears from it was removed: drop its page and its sitemap entry. A `since` filter only returns changed posts, so it never tells you about removals.\n\nRevnu counts your site as connected when it reads the first page of the unfiltered list. A site that only ever sends filtered requests is never counted: **I've Connected It** is refused, and its posts show as \"Not on site yet\" in the dashboard. See [Before you click I've Connected It](/docs/content-api).\n\n`400` for an unrecognised `type` or a non-numeric `since` or `limit`.", "tags": [ "Content API" ], "externalDocs": { "url": "https://revnu.com/docs/content-posts" }, "security": [ { "contentToken": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by content type, e.g. how_to.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Epoch milliseconds: only posts published or updated after this.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Default 50, up to 200.", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "description": "The cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ \"blog\": {…}, \"nav\": […], \"posts\": [summary, …], \"cursor\": \"…\" | null }. Each summary carries slug, title, contentType, metaDescription, canonicalPath, canonicalUrl, heroImageUrl, readingMinutes, publishedAt and updatedAt, which is everything a listing page or a sitemap needs. Keep requesting with ", "content": { "application/json": { "schema": { "type": "object", "properties": { "blog": { "type": "object", "properties": { "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorPhotoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUrl": { "type": "string" }, "blogSlug": { "type": "string" }, "creatorName": { "type": "string" }, "creatorOneliner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creatorTargetUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "flatContentPaths": { "type": "boolean" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trailingSlash": { "type": "boolean" } }, "required": [ "authorName", "authorPhotoUrl", "baseUrl", "blogSlug", "creatorName", "creatorOneliner", "creatorTargetUrl", "flatContentPaths", "logoUrl", "title", "trailingSlash" ] }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nav": { "type": "array", "items": { "$ref": "#/components/schemas/NavItem" } }, "posts": { "type": "array", "items": { "type": "object", "properties": { "canonicalPath": { "type": "string" }, "canonicalUrl": { "type": "string" }, "contentType": { "type": "string", "enum": [ "alternative", "blog", "comparison", "glossary", "how_to", "use_case" ] }, "heroImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "type": "number" }, "readingMinutes": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "canonicalPath", "canonicalUrl", "contentType", "heroImageUrl", "metaDescription", "publishedAt", "readingMinutes", "slug", "title", "updatedAt" ] } } }, "required": [ "blog", "cursor", "nav", "posts" ] } } } }, "400": { "description": "an unrecognised type, or a non-numeric since or limit on the list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing or malformed Authorization header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown or revoked token, or unknown slug; indistinguishable on purpose", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow down; Retry-After is set", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/content/v1/posts/{slug}": { "get": { "operationId": "contentPost", "summary": "Get a post", "description": "One post, render-ready: markdown and safe HTML, table of contents, head metadata, JSON-LD and related posts.\n\n**Response.** ```json\n{\n \"redirected\": false,\n \"blog\": { \"blogSlug\": \"…\", \"creatorName\": \"…\", \"authorName\": \"…\", \"logoUrl\": \"…\", \"baseUrl\": \"…\" },\n \"nav\": [{ \"type\": \"blog\", \"prefix\": \"blog\", \"label\": \"All\" }, { \"type\": \"how_to\", \"prefix\": \"guides\", \"label\": \"Guides\" }],\n \"post\": {\n \"slug\": \"graph-rag\",\n \"title\": \"…\",\n \"contentType\": \"how_to\",\n \"canonicalPath\": \"/guides/graph-rag\",\n \"canonicalUrl\": \"https://yourdomain.com/blog/guides/graph-rag\",\n \"metaDescription\": \"…\",\n \"authorName\": \"…\",\n \"readingMinutes\": 8,\n \"body\": { \"markdown\": \"…\", \"html\": \"…\" },\n \"toc\": [{ \"text\": \"…\", \"slug\": \"…\" }],\n \"heroImageUrl\": \"https://…\",\n \"faqItems\": [{ \"question\": \"…\", \"answer\": \"…\" }],\n \"citations\": [\"https://…\"],\n \"publishedAt\": 1753000000000,\n \"updatedAt\": 1753100000000\n },\n \"headMeta\": {\n \"title\": \"…\",\n \"description\": \"…\",\n \"canonical\": \"…\",\n \"robots\": \"index,follow\",\n \"openGraph\": { \"url\": \"…\", \"type\": \"article\", \"image\": { \"url\": \"…\", \"width\": 1200, \"height\": 630 } },\n \"twitter\": { \"card\": \"summary_large_image\", \"image\": { \"url\": \"…\" } }\n },\n \"jsonLd\": [{ \"@type\": \"Article\" }, { \"@type\": \"BreadcrumbList\" }, { \"@type\": \"FAQPage\" }],\n \"related\": [{ \"slug\": \"…\", \"title\": \"…\", \"contentType\": \"blog\", \"canonicalPath\": \"/…\" }]\n}\n```", "tags": [ "Content API" ], "externalDocs": { "url": "https://revnu.com/docs/content-post" }, "security": [ { "contentToken": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "``json { \"redirected\": false, \"blog\": { \"blogSlug\": \"…\", \"creatorName\": \"…\", \"authorName\": \"…\", \"logoUrl\": \"…\", \"baseUrl\": \"…\" }, \"nav\": [{ \"type\": \"blog\", \"prefix\": \"blog\", \"label\": \"All\" }, { \"type\": \"how_to\", \"prefix\": \"guides\", \"label\": \"Guides\" }], \"post\": { \"slug\": \"graph-rag\", \"title\": \"…\", \"", "content": { "application/json": { "schema": { "type": "object", "properties": { "blog": { "type": "object", "properties": { "authorName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "authorPhotoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUrl": { "type": "string" }, "blogSlug": { "type": "string" }, "creatorName": { "type": "string" }, "creatorOneliner": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "creatorTargetUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "flatContentPaths": { "type": "boolean" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trailingSlash": { "type": "boolean" } }, "required": [ "authorName", "authorPhotoUrl", "baseUrl", "blogSlug", "creatorName", "creatorOneliner", "creatorTargetUrl", "logoUrl", "title" ] }, "headMeta": { "type": "object", "properties": { "canonical": { "type": "string" }, "description": { "type": "string" }, "openGraph": { "type": "object", "properties": { "authors": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "image": { "type": "object", "properties": { "alt": { "type": "string" }, "height": { "type": "number" }, "url": { "type": "string" }, "width": { "type": "number" } }, "required": [ "alt", "height", "url", "width" ] }, "locale": { "type": "string" }, "modifiedTime": { "type": "string" }, "publishedTime": { "type": "string" }, "siteName": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "url": { "type": "string" } }, "required": [ "authors", "description", "image", "locale", "modifiedTime", "publishedTime", "siteName", "title", "type", "url" ] }, "robots": { "type": "string" }, "title": { "type": "string" }, "twitter": { "type": "object", "properties": { "card": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "object", "properties": { "alt": { "type": "string" }, "url": { "type": "string" } }, "required": [ "alt", "url" ] }, "title": { "type": "string" } }, "required": [ "card", "description", "image", "title" ] } }, "required": [ "canonical", "description", "openGraph", "robots", "title", "twitter" ] }, "jsonLd": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "nav": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "prefix": { "type": "string" }, "type": { "type": "string" } }, "required": [ "label", "prefix", "type" ] } }, "post": { "type": "object", "properties": { "authorName": { "type": "string" }, "body": { "type": "object", "properties": { "html": { "type": "string" }, "markdown": { "type": "string" } }, "required": [ "html", "markdown" ] }, "canonicalPath": { "type": "string" }, "canonicalUrl": { "type": "string" }, "citations": { "type": "array", "items": { "type": "string" } }, "contentType": { "type": "string", "enum": [ "alternative", "blog", "comparison", "glossary", "how_to", "use_case" ] }, "faqItems": { "type": "array", "items": { "type": "object", "properties": { "answer": { "type": "string" }, "question": { "type": "string" } }, "required": [ "answer", "question" ] } }, "heroImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "type": "number" }, "readingMinutes": { "type": "number" }, "slug": { "type": "string" }, "title": { "type": "string" }, "toc": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "text": { "type": "string" } }, "required": [ "slug", "text" ] } }, "updatedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "authorName", "body", "canonicalPath", "canonicalUrl", "citations", "contentType", "faqItems", "heroImageUrl", "metaDescription", "publishedAt", "readingMinutes", "slug", "title", "toc", "updatedAt" ] }, "redirected": { "type": "boolean" }, "related": { "type": "array", "items": { "type": "object", "properties": { "canonicalPath": { "type": "string" }, "contentType": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "canonicalPath", "contentType", "slug", "title" ] } } }, "required": [ "blog", "headMeta", "jsonLd", "nav", "post", "redirected", "related" ] } } } }, "400": { "description": "an unrecognised type, or a non-numeric since or limit on the list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing or malformed Authorization header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown or revoked token, or unknown slug; indistinguishable on purpose", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "slow down; Retry-After is set", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/measurement/events": { "post": { "operationId": "eventApi", "summary": "Send Events", "description": "Tell Revnu from your server when a visitor signs up, books a call or pays, so the result is tied back to where they came from.\n\n**Response.** ```json\n{\n \"accepted\": true,\n \"matched\": false,\n \"counted\": false,\n \"not_counted_reason\": \"\\\"signup\\\" is not in this site's win definition, which counts \\\"trial_started\\\". It was recorded, but it will not count as a win until the definition in Revnu includes it.\",\n \"duplicate\": false,\n \"enriched\": false,\n \"event_id\": \"signup_8412\",\n \"event_name\": \"signup\",\n \"roles\": [],\n \"attribution_status\": \"pending\"\n}\n```\n\n- `counted` says whether the event counts as a win under your site's win definition.\n- `not_counted_reason` appears when an event can never count because the definition does not include its `event_name`. Change the definition in Revnu, or send the event it names.\n- `matched` says whether the event was credited to one of your Revnu ad campaigns. It stays `false` until you run campaigns through Revnu, and that is expected.\n- `qualification_status` appears when your definition has requirements, such as a work email or company size: `qualified`, `not_qualified`, or `pending_evidence` while Revnu still researches the company. `qualification_missing` names what's missing.\n\n| Code | Meaning |\n|---|---|\n| 200 | Recorded and credited to one of your Revnu ad campaigns, or a duplicate of an event already recorded |\n| 202 | Recorded, not credited to a campaign. Check `counted` to see whether it counts as a win |\n| 401 | Missing or invalid event key |\n| 409 | The same `event_id` was sent before with different values |\n| 413 | Body over 64 KB |\n| 422 | A field failed validation; `error` says which |\n| 429 | Rate limited; retry later with the same `event_id` |\n\n### Why an event didn't count\n\n| `not_counted_reason` starts with | What it means | Fix |\n|---|---|---|\n| `This site has no win definition yet` | No outcome is set up, so nothing counts. | Set one up in **Ads → Revnu Tag**. See [set up outcomes](/docs/set-up-outcomes). |\n| `\"signup\" is not in this site's win definition` (with your event name) | The event arrived, but your outcomes count other event names. The message lists them. | Send the event name it lists, or ask Revnu to add this one as an outcome and approve the change in **Ads → Revnu Tag**. |\n\n`counted: false` with no `not_counted_reason` means the event name is in your definition but this one didn't meet its requirements, or Revnu is still researching the company. Check `qualification_status` and `qualification_missing`. A refund or cancellation sent with `reversal_of` never counts as a win itself.", "tags": [ "Measurement" ], "externalDocs": { "url": "https://revnu.com/docs/event-api" }, "security": [ { "eventKey": [] } ], "requestBody": { "required": true, "description": "| Field | Required | Notes |\n|---|---|---|\n| `event_id` | yes | Your stable id for this event. 1-128 letters, digits, `.`, `_`, `:` or `-`. Sending the same id again is safe: it is reported as a duplicate, not counted twice. |\n| `event_name` | yes | Lowercase snake_case, for example `signup`, `demo_booked`, `purchase`. |\n| `occurred_at` | no | ISO 8601 date or milliseconds. Defaults to when Revnu receives it. |\n| `anonymous_id` | no | `window.revnu.anonymousId` from the visit. |\n| `consent_state` | no | `granted`, `denied` or `pending`: the visitor's choice saved with the signup, booking or checkout. Every event except `denied` is sent to your ad platforms. |\n| `google_ad_user_data`, `google_ad_personalization` | no | `granted`, `denied` or `unknown`. Google Ads receives every event except one where `google_ad_user_data` is `denied`. |\n| `gclid`, `gbraid`, `wbraid`, `fbclid`, `ttclid`, `_ttp`, `twclid`, `li_fat_id`, `msclkid`, `rdt_cid` | no | Ad click ids or Pixel cookies you stored yourself. Only needed when the visit cannot be joined by `anonymous_id`, for example when the tag was blocked. |\n| `email`, `phone`, `external_user_id` | no | Normalized and hashed for matching. |\n| `amount`, `currency` | no | Send both, for example `49` and `\"USD\"`. |\n| `properties` | no | An object of extra facts, for example `{ \"plan\": \"pro\" }`. |\n| `reversal_of` | no | The `event_id` of an earlier event this one cancels, such as a refund. Repeat the original `amount` and `currency`. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Recorded and credited to one of your Revnu ad campaigns, or a duplicate of an event already recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "attribution_status": { "type": "string", "enum": [ "ambiguous", "direct", "outside_window", "pending", "stitched", "unattributed" ] }, "campaign_id": { "type": "string" }, "counted": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "enriched": { "type": "boolean" }, "event_id": { "type": "string" }, "event_name": { "type": "string" }, "matched": { "type": "boolean" }, "not_counted_reason": { "type": "string" }, "qualification_missing": { "type": "array", "items": { "type": "string" } }, "qualification_status": { "type": "string", "enum": [ "not_qualified", "pending_evidence", "qualified" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "business", "diagnostic", "optimization", "qualified", "reversal" ] } } }, "required": [ "accepted", "attribution_status", "counted", "duplicate", "enriched", "event_id", "event_name", "matched", "roles" ] } } } }, "202": { "description": "Recorded, not credited to a campaign. Check counted to see whether it counts as a win", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean", "const": true }, "attribution_status": { "type": "string", "enum": [ "ambiguous", "direct", "outside_window", "pending", "stitched", "unattributed" ] }, "campaign_id": { "type": "string" }, "counted": { "type": "boolean" }, "duplicate": { "type": "boolean" }, "enriched": { "type": "boolean" }, "event_id": { "type": "string" }, "event_name": { "type": "string" }, "matched": { "type": "boolean" }, "not_counted_reason": { "type": "string" }, "qualification_missing": { "type": "array", "items": { "type": "string" } }, "qualification_status": { "type": "string", "enum": [ "not_qualified", "pending_evidence", "qualified" ] }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "business", "diagnostic", "optimization", "qualified", "reversal" ] } } }, "required": [ "accepted", "attribution_status", "counted", "duplicate", "enriched", "event_id", "event_name", "matched", "roles" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing or invalid event key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The same event_id was sent before with different values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 64 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A field failed validation; error says which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; retry later with the same event_id", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/preview": { "post": { "operationId": "requestPreview", "summary": "Request a preview", "description": "Research a business's website with no account and no token. Returns a previewId to poll. Capped per caller, per site and per day; a site researched in the last day is reused.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/preview" }, "security": [], "requestBody": { "required": true, "description": "| Field | Type | Meaning |\n|---|---|---|\n| `website` | string, required | The business's own website, such as `acme.com`. Up to 300 characters. Revnu researches the homepage of the host that answers, whatever path you give. No other fields are allowed. |", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "202": { "description": "{ previewId, status, poll }. status is researching, or ready when someone previewed the same site in the last day. Poll poll.", "content": { "application/json": { "schema": { "type": "object", "properties": { "poll": { "type": "string" }, "previewId": { "type": "string" }, "status": { "type": "string", "enum": [ "failed", "ready", "researching" ] } }, "required": [ "poll", "previewId", "status" ] } } } }, "400": { "description": "The body isn't JSON, website is missing or too long, or there is an extra field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_website with a message: the address isn't a public website, the site doesn't exist or isn't answering, it is a social network profile rather than the business's own site, or it is revnu.com.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited with a message. Wait for Retry-After (seconds) before trying again.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Something failed on Revnu's side. Honour Retry-After and retry the same call.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/preview/{previewId}": { "get": { "operationId": "getPreview", "summary": "Read a preview", "description": "Where the research is (researching, ready, failed, claimed or expired), the review rows with their sources once ready, and the claim_url that turns the research into an account.", "tags": [ "API Reference" ], "externalDocs": { "url": "https://revnu.com/docs/preview" }, "security": [], "parameters": [ { "name": "previewId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "{ preview } in any status but expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "anyOf": [ { "type": "object", "properties": { "businessName": { "type": "string" }, "claim_url": { "type": "string" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "previewId": { "type": "string" }, "research": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "string" } }, "step": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "findings", "step" ] }, "status": { "type": "string", "const": "researching" }, "website": { "type": "string" } }, "required": [ "businessName", "claim_url", "expiresAt", "next", "previewId", "research", "status", "website" ] }, { "type": "object", "properties": { "businessName": { "type": "string" }, "claim_url": { "type": "string" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "previewId": { "type": "string" }, "review": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "found": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "fact", "question", "value" ] }, "label": { "type": "string" }, "question": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "found", "id", "kind", "label", "sources" ] } } }, "required": [ "findings", "rows" ] }, "status": { "type": "string", "const": "ready" }, "website": { "type": "string" } }, "required": [ "businessName", "claim_url", "expiresAt", "next", "previewId", "review", "status", "website" ] }, { "type": "object", "properties": { "businessName": { "type": "string" }, "claim_url": { "type": "string" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "previewId": { "type": "string" }, "status": { "type": "string", "const": "failed" }, "website": { "type": "string" } }, "required": [ "businessName", "claim_url", "expiresAt", "next", "previewId", "status", "website" ] }, { "type": "object", "properties": { "businessName": { "type": "string" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "previewId": { "type": "string" }, "status": { "type": "string", "const": "claimed" }, "website": { "type": "string" } }, "required": [ "businessName", "expiresAt", "next", "previewId", "status", "website" ] }, { "type": "object", "properties": { "businessName": { "type": "string" }, "expiresAt": { "type": "string" }, "next": { "type": "string" }, "previewId": { "type": "string" }, "status": { "type": "string", "const": "expired" }, "website": { "type": "string" } }, "required": [ "businessName", "expiresAt", "next", "previewId", "status", "website" ] } ] } }, "required": [ "preview" ] } } } }, "404": { "description": "not_found: no preview has that id. Expired previews are deleted daily, so an old id ends up here too.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The preview expired. The body still says so in preview.status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "personalToken": { "type": "http", "scheme": "bearer", "bearerFormat": "rvp_…", "description": "Personal API token from Settings → Developers, scoped per token. https://revnu.com/docs/authentication" }, "contentToken": { "type": "http", "scheme": "bearer", "bearerFormat": "rvc_…", "description": "Read-only Content API token. https://revnu.com/docs/content-api" }, "eventKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rsk_live_…", "description": "Server-side event key for the Event API. https://revnu.com/docs/event-api" } }, "schemas": { "AdsData": { "type": "object", "properties": { "changesInWindow": { "type": "number" }, "charter": { "type": "object", "properties": { "currency": { "type": "string" }, "dailyCap": { "type": "number" }, "learningBudget": { "type": "number" }, "status": { "type": "string", "enum": [ "approved", "draft", "revoked", "superseded" ] } }, "required": [ "currency", "dailyCap", "learningBudget", "status" ] }, "drafts": { "type": "number" }, "experiment": { "type": "object", "properties": { "batchEnd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "decisionDue": { "type": "boolean" }, "name": { "type": "string" }, "primaryOutcome": { "type": "string", "enum": [ "clicks", "delivery", "qualified_leads", "revenue" ] }, "status": { "type": "string", "enum": [ "complete", "draft", "paused", "running" ] }, "strategy": { "type": "string", "enum": [ "adaptive", "infeasible", "parallel", "sequential" ] } }, "required": [ "batchEnd", "name", "primaryOutcome", "status", "strategy" ] }, "liveCampaigns": { "type": "number" }, "scoreboard": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/AdsScoreboardData" } }, "required": [ "available", "data" ] } ] }, "spend": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "properties": { "clicks": { "type": "number" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "impressions": { "type": "number" }, "spendAmount": { "type": "number" } }, "required": [ "clicks", "currency", "impressions", "spendAmount" ] } }, "required": [ "available", "data" ] } ] }, "tried": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number" }, "concept": { "type": "string" }, "decision": { "type": "string" }, "rationale": { "type": "string" } }, "required": [ "at", "concept", "decision", "rationale" ] } } }, "required": [ "changesInWindow", "drafts", "liveCampaigns", "spend" ] }, "AdsScoreboardData": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "arm": { "type": "string" }, "campaignId": { "type": "string" }, "clicks": { "type": "number" }, "conversions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "impressions": { "type": "number" }, "name": { "type": "string" }, "provider": { "type": "string" }, "spend": { "type": "number" } }, "required": [ "clicks", "conversions", "currency", "impressions", "name", "provider", "spend" ] } }, "days": { "type": "number" } }, "required": [ "campaigns", "days" ] }, "AeoData": { "type": "object", "properties": { "byEngine": { "type": "array", "items": { "type": "object", "properties": { "engine": { "type": "string" }, "mentionRatePct": { "type": "number" }, "runs": { "type": "number" } }, "required": [ "engine", "mentionRatePct", "runs" ] } }, "deltas": { "type": "object", "properties": { "citationSharePts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shareOfVoicePts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "visibilityPts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "citationSharePts", "shareOfVoicePts", "visibilityPts" ] }, "incomplete": { "type": "boolean" }, "measuredThrough": { "type": "string" }, "prior7d": { "anyOf": [ { "$ref": "#/components/schemas/AeoPeriodData" }, { "type": "null" } ] }, "scoreboard": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/AeoScoreboardData" } }, "required": [ "available", "data" ] } ] }, "sentiment": { "anyOf": [ { "type": "object", "properties": { "bad": { "type": "number" }, "good": { "type": "number" }, "neutral": { "type": "number" } }, "required": [ "bad", "good", "neutral" ] }, { "type": "null" } ] }, "trackedPrompts": { "type": "number" }, "window7d": { "$ref": "#/components/schemas/AeoPeriodData" } }, "required": [ "byEngine", "deltas", "incomplete", "measuredThrough", "prior7d", "sentiment", "trackedPrompts", "window7d" ] }, "AeoPeriodData": { "type": "object", "properties": { "citationSharePct": { "type": "number" }, "shareOfVoicePct": { "type": "number" }, "totalRuns": { "type": "number" }, "visibilityPct": { "type": "number" } }, "required": [ "citationSharePct", "shareOfVoicePct", "totalRuns", "visibilityPct" ] }, "AeoScoreboardData": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "type": "object", "properties": { "contentAgeDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deltaPts": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mentionRatePct": { "type": "number" }, "runs": { "type": "number" }, "text": { "type": "string" } }, "required": [ "contentAgeDays", "deltaPts", "mentionRatePct", "runs", "text" ] } } }, "required": [ "prompts" ] }, "BackgroundTask": { "type": "object", "properties": { "endedAt": { "type": "number" }, "id": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "type": "number" }, "state": { "$ref": "#/components/schemas/BackgroundTaskState" } }, "required": [ "id", "label", "startedAt", "state" ] }, "BackgroundTaskState": { "type": "string", "enum": [ "done", "failed", "running", "stopped" ] }, "EmailData": { "type": "object", "properties": { "draftsAwaiting": { "type": "number" }, "replies": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "properties": { "bounces": { "type": "number" }, "byIntent": { "$ref": "#/components/schemas/RepliesByIntent" }, "repliedContacts": { "type": "array", "items": { "$ref": "#/components/schemas/RepliedContact" } }, "replies": { "type": "number" } }, "required": [ "bounces", "replies" ] } }, "required": [ "available", "data" ] } ] }, "sent": { "type": "number" }, "sentBaseline": { "type": "number" }, "tracking": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/EmailTrackingData" } }, "required": [ "available", "data" ] } ] } }, "required": [ "draftsAwaiting", "replies", "sent", "sentBaseline", "tracking" ] }, "EmailTrackingData": { "type": "object", "properties": { "clicks": { "type": "object", "properties": { "ambiguousTotal": { "type": "number" }, "ambiguousUniqueEmails": { "type": "number" }, "automatedTotal": { "type": "number" }, "topUrls": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "number" }, "url": { "type": "string" } }, "required": [ "clicks", "url" ] } }, "total": { "type": "number" }, "uniqueEmails": { "type": "number" } }, "required": [ "ambiguousTotal", "ambiguousUniqueEmails", "automatedTotal", "topUrls", "total", "uniqueEmails" ] }, "engagedLeads": { "type": "array", "items": { "type": "object", "properties": { "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daySlot": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstOpenAt": { "type": "number" }, "opens": { "type": "number" } }, "required": [ "contactEmail", "daySlot", "domain", "firstOpenAt", "opens" ] } }, "opens": { "type": "object", "properties": { "ambiguousTotal": { "type": "number" }, "ambiguousUniqueEmails": { "type": "number" }, "automatedTotal": { "type": "number" }, "total": { "type": "number" }, "uniqueEmails": { "type": "number" } }, "required": [ "ambiguousTotal", "ambiguousUniqueEmails", "automatedTotal", "total", "uniqueEmails" ] } }, "required": [ "clicks", "engagedLeads", "opens" ] }, "HarnessData": { "type": "object", "properties": { "oldestPendingAgeHours": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "queueNeedsRevision": { "type": "number" }, "queuePending": { "type": "number" }, "wakesFailed": { "type": "number" }, "wakesFired": { "type": "number" } }, "required": [ "oldestPendingAgeHours", "queueNeedsRevision", "queuePending", "wakesFailed", "wakesFired" ] }, "LinkedinData": { "type": "object", "properties": { "accepts": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] } }, "required": [ "available", "data" ] } ] }, "alreadyConnectedHits": { "type": "number" }, "baseline": { "type": "object", "properties": { "dms": { "type": "number" }, "inmails": { "type": "number" }, "invites": { "type": "number" } }, "required": [ "dms", "inmails", "invites" ] }, "chatReplies": { "type": "number" }, "health": { "type": "object", "properties": { "inviteHeadroom": { "type": "number" }, "needsReauth": { "type": "boolean" }, "pauseReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pausedUntil": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "inviteHeadroom", "needsReauth", "pauseReason", "pausedUntil" ] }, "inmails": { "type": "number" }, "invites": { "type": "number" }, "newDMs": { "type": "number" }, "replies": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "properties": { "count": { "type": "number" } }, "required": [ "count" ] } }, "required": [ "available", "data" ] } ] }, "scoreboard": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/LinkedinScoreboardData" } }, "required": [ "available", "data" ] } ] } }, "required": [ "accepts", "alreadyConnectedHits", "baseline", "chatReplies", "health", "inmails", "invites", "newDMs", "replies" ] }, "LinkedinPersonAccount": { "anyOf": [ { "type": "object", "properties": { "account": { "type": "string" }, "connected": { "type": "boolean" }, "connectedAs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invite": { "anyOf": [ { "type": "object", "properties": { "at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "direction": { "type": [ "string", "null" ], "enum": [ "received", "sent", null ] }, "status": { "type": [ "string", "null" ], "enum": [ "ignored", "pending", "withdrawn", null ] } }, "required": [ "at", "direction", "status" ] }, { "type": "null" } ] }, "lastReplyAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPersonMessage" } }, "messagesTruncated": { "type": "boolean" }, "revnuInvite": { "anyOf": [ { "type": "object", "properties": { "acceptedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sentAt": { "type": "number" }, "withdrawnAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "acceptedAt", "sentAt", "withdrawnAt" ] }, { "type": "null" } ] }, "state": { "type": "string", "const": "ok" } }, "required": [ "account", "connected", "connectedAs", "invite", "lastReplyAt", "messages", "messagesTruncated", "revnuInvite", "state" ] }, { "type": "object", "properties": { "account": { "type": "string" }, "connectedAs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" }, "retryAt": { "type": "number" }, "state": { "type": "string", "const": "paced" } }, "required": [ "account", "connectedAs", "message", "retryAt", "state" ] }, { "type": "object", "properties": { "account": { "type": "string" }, "connectedAs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" }, "state": { "type": "string", "const": "error" } }, "required": [ "account", "connectedAs", "message", "state" ] }, { "type": "object", "properties": { "account": { "type": "string" }, "connectedAs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "needs_reauth", "not_connected" ] } }, "required": [ "account", "connectedAs", "state" ] } ] }, "LinkedinPersonMessage": { "type": "object", "properties": { "at": { "type": "number" }, "from": { "type": "string", "enum": [ "them", "you" ] }, "kind": { "type": "string", "enum": [ "event", "inmail", "invitation", "message" ] }, "sentBy": { "type": [ "string", "null" ], "enum": [ "agent", "person", null ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "at", "from", "kind", "sentBy", "text" ] }, "LinkedinScoreboardData": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "accepts": { "type": "number" }, "invites": { "type": "number" }, "label": { "type": "string" }, "maturedInvites": { "type": "number" } }, "required": [ "accepts", "invites", "label", "maturedInvites" ] } } }, "required": [ "campaigns" ] }, "MessageStatus": { "type": "string", "enum": [ "failed", "queued", "replied", "running" ] }, "NavItem": { "type": "object", "properties": { "label": { "type": "string" }, "prefix": { "type": "string" }, "type": { "type": "string", "enum": [ "alternative", "blog", "comparison", "glossary", "how_to", "use_case" ] } }, "required": [ "label", "prefix", "type" ] }, "OutboundScoreboardData": { "type": "object", "properties": { "breakdownUnavailable": { "type": "boolean" }, "readAt": { "type": "number" }, "readyIsFloor": { "type": "boolean" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "bounced": { "type": "number" }, "delivered": { "type": "number" }, "drafted": { "type": "number" }, "experiment": { "type": "object", "properties": { "cap": { "type": "number" }, "used": { "type": "number" } }, "required": [ "cap", "used" ] }, "pending": { "type": "number" }, "ready": { "type": "number" }, "replied": { "type": "number" }, "route": { "type": "string" }, "sequence": { "anyOf": [ { "$ref": "#/components/schemas/RouteSequence" }, { "type": "null" } ] } }, "required": [ "bounced", "delivered", "pending", "replied", "route" ] } } }, "required": [ "routes" ] }, "OutreachError": { "type": "object", "properties": { "detail": { "type": "string" }, "kind": { "$ref": "#/components/schemas/OutreachErrorKind" }, "provider": { "type": "string" }, "retryAfterSec": { "type": "number" } }, "required": [ "detail", "kind" ] }, "OutreachErrorKind": { "type": "string", "enum": [ "bad_input", "budget_exhausted", "missing_key", "network", "not_found", "out_of_credits", "rate_limited", "schema_drift", "upstream_5xx" ] }, "ProviderUsage": { "type": "object", "properties": { "attempts": { "type": "array", "items": { "type": "string" } }, "calls": { "type": "number" }, "costUsd": { "type": "number" }, "creditsUsed": { "type": "number" }, "operation": { "type": "string" }, "provider": { "type": "string" } }, "required": [ "calls", "operation", "provider" ] }, "PublishResult": { "type": "object", "properties": { "liveUrl": { "type": "string" }, "ok": { "type": "boolean", "const": true }, "slug": { "type": "string" }, "waitingForSite": { "type": "boolean", "const": true } }, "required": [ "liveUrl", "ok", "slug" ] }, "RepliedContact": { "type": "object", "properties": { "agoDays": { "type": "number" }, "company": { "type": "string" }, "intent": { "type": "string", "enum": [ "interested", "not_interested", "other", "out_of_office", "referral", "unsubscribe" ] }, "who": { "type": "string" } }, "required": [ "agoDays", "company", "who" ] }, "RepliesByIntent": { "type": "array", "items": { "type": "object", "properties": { "count": { "type": "number" }, "intent": { "type": "string", "enum": [ "interested", "not_interested", "other", "out_of_office", "referral", "unclassified", "unsubscribe" ] } }, "required": [ "count", "intent" ] } }, "ResultsWindowResult": { "anyOf": [ { "type": "object", "properties": { "ads": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/AdsData" } }, "required": [ "available", "data" ] } ] }, "aeo": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/AeoData" } }, "required": [ "available", "data" ] } ] }, "baseline": { "$ref": "#/components/schemas/TimeWindow" }, "email": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/EmailData" } }, "required": [ "available", "data" ] } ] }, "harness": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/HarnessData" } }, "required": [ "available", "data" ] } ] }, "linkedin": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/LinkedinData" } }, "required": [ "available", "data" ] } ] }, "outbound": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/OutboundScoreboardData" } }, "required": [ "available", "data" ] } ] }, "seo": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/SeoData" } }, "required": [ "available", "data" ] } ] }, "window": { "$ref": "#/components/schemas/TimeWindow" } }, "required": [ "ads", "aeo", "baseline", "email", "harness", "linkedin", "seo", "window" ] }, { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "deleted", "demo" ] }, "skip": { "type": "boolean", "const": true } }, "required": [ "reason", "skip" ] } ] }, "ReviewActionVerb": { "type": "string", "enum": [ "answer", "approve", "choose", "dismiss", "request_changes", "send", "snooze" ] }, "ReviewCardWire": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewActionVerb" } }, "autoResolveAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "budgetChange": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string" }, "monthlyCap": { "type": "number" }, "previousMonthlyCap": { "type": "number" } }, "required": [ "currency", "monthlyCap", "previousMonthlyCap" ] }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "approval", "choice", "follow_up", "question", "review", "setup", "update" ] }, "leadContactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leadId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } }, { "type": "null" } ] }, "payload": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primaryLabel": { "type": "string" }, "priority": { "type": "string", "enum": [ "high", "low", "normal" ] }, "prompt": { "type": "string" }, "resolution": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "string" }, "decidedBy": { "type": "string", "enum": [ "admin", "agent", "auto_ship", "chat", "customer", "same_recipient", "standing_approval" ] }, "note": { "type": "string" }, "optionValues": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" } }, "required": [ "action" ] }, { "type": "null" } ] }, "resolvedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "snoozedUntil": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sourceType": { "type": [ "string", "null" ], "enum": [ "ads_budget", "ads_launch", "agent", "blog_draft", "blog_edit", "booking_link", "gift_send", "gmail_draft", "gmail_reply", "lead", "lead_contact", "linkedin_invite", "linkedin_message", "measurement_charter", "memory_rule", "outbound_setup", "outreach_sequence", "reddit_comment", "system", null ] }, "status": { "type": "string", "enum": [ "cancelled", "dismissed", "done", "expired", "needs_revision", "pending", "snoozed" ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "textInput": { "anyOf": [ { "type": "object", "properties": { "placeholder": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" } }, "required": [ "placeholder", "required" ] }, { "type": "null" } ] }, "title": { "type": "string" }, "updatedAt": { "type": "number" } }, "required": [ "actions", "autoResolveAt", "budgetChange", "createdAt", "detail", "dueAt", "id", "kind", "leadContactId", "leadId", "options", "payload", "postId", "primaryLabel", "priority", "prompt", "resolvedAt", "snoozedUntil", "status", "summary", "textInput", "title", "updatedAt" ] }, "RouteSequence": { "type": "object", "properties": { "approval": { "type": "string", "enum": [ "approved", "needs_review" ] }, "updatedAt": { "type": "number" } }, "required": [ "approval", "updatedAt" ] }, "SectionUnavailableReason": { "type": "string", "enum": [ "measurement_stalled", "needs_reauth", "no_blog", "no_campaigns", "no_data_yet", "no_writer_yet", "not_connected", "not_tracked", "read_failed", "tracking_off" ] }, "SeoData": { "type": "object", "properties": { "genCostCents": { "type": "number" }, "gsc": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "type": "object", "properties": { "clicks": { "type": "number" }, "from": { "type": "string" }, "impressions": { "type": "number" }, "ourPosts": { "anyOf": [ { "type": "object", "properties": { "clicks": { "type": "number" }, "impressions": { "type": "number" }, "prevClicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "top": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "number" }, "impressions": { "type": "number" }, "path": { "type": "string" } }, "required": [ "clicks", "impressions", "path" ] } } }, "required": [ "clicks", "impressions", "prevClicks", "top" ] }, { "type": "null" } ] }, "prevClicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "through": { "type": "string" } }, "required": [ "clicks", "from", "impressions", "ourPosts", "prevClicks", "through" ] } }, "required": [ "available", "data" ] } ] }, "postsFailed": { "type": "number" }, "postsHeld": { "type": "number" }, "postsPublished": { "type": "number" }, "refreshes": { "type": "object", "properties": { "applied": { "type": "number" }, "skipped": { "type": "number" } }, "required": [ "applied", "skipped" ] }, "scoreboard": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "const": false }, "reason": { "$ref": "#/components/schemas/SectionUnavailableReason" } }, "required": [ "available", "reason" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "const": true }, "caveats": { "type": "array", "items": { "type": "string" } }, "data": { "$ref": "#/components/schemas/SeoScoreboardData" } }, "required": [ "available", "data" ] } ] }, "views": { "type": "number" }, "viewsPrev": { "type": "number" } }, "required": [ "genCostCents", "gsc", "postsFailed", "postsHeld", "postsPublished", "refreshes", "views", "viewsPrev" ] }, "SeoScoreboardData": { "type": "object", "properties": { "from": { "type": "string" }, "through": { "type": "string" }, "types": { "type": "array", "items": { "type": "object", "properties": { "clicks": { "type": "number" }, "impressions": { "type": "number" }, "pages": { "type": "number" }, "prevClicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "prevImpressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" } }, "required": [ "clicks", "impressions", "pages", "prevClicks", "prevImpressions", "type" ] } }, "zeroClickPages": { "type": "array", "items": { "type": "object", "properties": { "impressions": { "type": "number" }, "path": { "type": "string" } }, "required": [ "impressions", "path" ] } } }, "required": [ "from", "through", "types", "zeroClickPages" ] }, "SetupStage": { "type": "string", "enum": [ "done", "payment", "researching", "review", "start", "website" ] }, "TimeWindow": { "type": "object", "properties": { "from": { "type": "number" }, "to": { "type": "number" } }, "required": [ "from", "to" ] }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "A code such as `forbidden`, or a sentence for a 400." }, "message": { "type": "string" }, "requiredScope": { "type": "string", "description": "On 403: the scope the route needs." }, "actions": { "type": "array", "items": { "type": "string" }, "description": "On 409 invalid_action: the verbs the card accepts now." } } } }, "responses": { "BadRequest": { "description": "The request is malformed; the error names the problem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, malformed, unknown or revoked token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "SetupPending": { "description": "`setup_pending`: the account hasn't started its trial. Finish setup with `GET /setup`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The token lacks the scope in `requiredScope`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown id, or another account's id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "A settled refusal: `invalid_action` (see `actions`) or `rejected`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limited.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "Temporarily unavailable; retry the same call.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }