{ "openapi": "3.1.0", "info": { "title": "NorReach API", "version": "1.0.0", "description": "Control your NorReach workspace from your own systems. Every request uses an API key from Settings › API & webhooks and acts as the person who created it, within the key's scopes and that person's role." }, "externalDocs": { "description": "The NorReach developer docs", "url": "https://docs.norreach.app/" }, "servers": [ { "url": "https://api.norreach.app/v1" } ], "tags": [ { "name": "Ads" }, { "name": "Analytics" }, { "name": "Approvals" }, { "name": "Audit log" }, { "name": "Automations" }, { "name": "Calls" }, { "name": "Campaigns" }, { "name": "Contacts" }, { "name": "Credits" }, { "name": "Deals" }, { "name": "Do-not-contact" }, { "name": "Inbox" }, { "name": "Landing pages" }, { "name": "Lists" }, { "name": "Meetings" }, { "name": "Nora" }, { "name": "Phone numbers" }, { "name": "Plans" }, { "name": "Social" }, { "name": "Team" }, { "name": "Templates" }, { "name": "Webhooks" }, { "name": "Workspace" } ], "paths": { "/ad-accounts": { "get": { "operationId": "list_ad_accounts", "summary": "List ad accounts", "description": "The ad accounts connected to the workspace, per network: name, currency (every amount on the account is in it), time zone, sync state and whether Nora's launches can be published to it from NorReach now. A Meta account's spending limit: GET / PUT /ad-accounts/{id}/spending-limit. Connecting accounts and billing are managed in the app and in the ad network — never through the API.\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "network", "in": "query", "required": false, "description": "meta, tiktok, reddit or chatgpt.", "schema": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] } } ], "responses": { "200": { "description": "List ad accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "object": { "type": "string", "const": "ad_account" }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "network_name": { "type": "string" }, "name": { "type": "string" }, "account_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ad network's own number for the account, as the app shows it." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217; every amount on this account is in it." }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "syncing", "error" ] }, "is_default": { "type": "boolean" }, "can_publish": { "type": "boolean", "description": "Nora's launches can be published to this account from NorReach right now." }, "last_synced_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "sync_problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A plain sentence when the last sync failed." } }, "required": [ "id", "object", "network", "network_name", "name", "account_number", "currency", "timezone", "status", "is_default", "can_publish", "last_synced_at", "sync_problem" ], "additionalProperties": false, "description": "A connected ad account. Connecting, limits and billing are managed in the app and in the ad network." } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "object": "ad_account", "network": "meta", "network_name": "Meta", "name": "Example Care", "account_number": "act_1234567890", "currency": "SEK", "timezone": "Europe/Stockholm", "status": "active", "is_default": true, "can_publish": true, "last_synced_at": "2026-11-05T09:15:02.000Z", "sync_problem": null } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/ad-accounts/{id}/spending-limit": { "get": { "operationId": "get_ad_account_spending_limit", "summary": "An ad account's spending limit", "description": "The ad account's own spending limit and the spend counted against it since the last reset, read live from the network, in minor units of the account's currency. At the limit the network stops every ad in the account. Meta accounts; other networks answer 422 ad_network_unsupported.\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "An ad account's spending limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_account_spending_limit" }, "ad_account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Null = no account spending limit." }, "spent": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Spend counted against the limit since it was last reset." }, "level": { "type": "string", "enum": [ "none", "ok", "near", "reached", "unknown" ], "description": "`near` from 80 % of the limit; at `reached` the network stops every ad in the account." } }, "required": [ "object", "ad_account_id", "network", "currency", "limit", "spent", "level" ], "additionalProperties": false, "description": "The ad account's own spending limit, read live from the network." }, "example": { "object": "ad_account_spending_limit", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "network": "meta", "currency": "SEK", "limit": { "amount_minor": 5000000, "currency": "SEK" }, "spent": { "amount_minor": 1254000, "currency": "SEK" }, "level": "ok" } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`ad_network_unsupported` — This can't be done on this ad network from NorReach yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "D", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false }, "put": { "operationId": "set_ad_account_spending_limit", "summary": "Set or remove an ad account's spending limit", "description": "Sets the ad account's spending limit (`limit` in integer minor units of the account's currency, 1 to 10,000,000 in major units) or removes it (`limit: null` — ads then spend up to their own budgets). The same core as Channels › Ad account's spending controls: owners and admins only (the ads:limits scope), a currency the network's table lists — never a guessed scale. Meta accounts; other networks answer 422 ad_network_unsupported. `dry_run=true` checks it and changes nothing.\n\nRequires the `ads:limits` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:limits" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Integer minor units in the ad account's currency (1 to 10,000,000 in major units), or null to remove the limit." } }, "required": [ "limit" ], "additionalProperties": false }, "example": { "limit": { "amount_minor": 5000000, "currency": "SEK" } } } } }, "responses": { "200": { "description": "Set or remove an ad account's spending limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_account_spending_limit_action" }, "ad_account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "set", "remove", "reset" ] }, "dry_run": { "type": "boolean" }, "note": { "type": "string" }, "spending_limit": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "ad_account_spending_limit" }, "ad_account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Null = no account spending limit." }, "spent": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Spend counted against the limit since it was last reset." }, "level": { "type": "string", "enum": [ "none", "ok", "near", "reached", "unknown" ], "description": "`near` from 80 % of the limit; at `reached` the network stops every ad in the account." } }, "required": [ "object", "ad_account_id", "network", "currency", "limit", "spent", "level" ], "additionalProperties": false, "description": "The ad account's own spending limit, read live from the network." }, { "type": "null" } ] } }, "required": [ "object", "ad_account_id", "action", "dry_run", "note", "spending_limit" ], "additionalProperties": false }, "example": { "object": "ad_account_spending_limit_action", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "action": "set", "dry_run": false, "note": "Spending limit set to 50,000 SEK. Meta stops every ad in the account when it's reached.", "spending_limit": { "object": "ad_account_spending_limit", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "network": "meta", "currency": "SEK", "limit": { "amount_minor": 5000000, "currency": "SEK" }, "spent": { "amount_minor": 1254000, "currency": "SEK" }, "level": "ok" } } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request. · `ad_network_unsupported` — This can't be done on this ad network from NorReach yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:limits", "x-norreach-action": "ads.limits", "x-norreach-phase": "D", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/ad-accounts/{id}/spending-limit/reset": { "post": { "operationId": "reset_ad_account_spend", "summary": "Start a new spending-limit period", "description": "Sets the spend counted against the ad account's spending limit back to 0 — ads that stopped at the limit can spend again, up to it. Owners and admins only (ads:limits). Meta accounts; other networks answer 422 ad_network_unsupported. `dry_run=true` checks it and changes nothing.\n\nRequires the `ads:limits` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:limits" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Start a new spending-limit period", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_account_spending_limit_action" }, "ad_account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "set", "remove", "reset" ] }, "dry_run": { "type": "boolean" }, "note": { "type": "string" }, "spending_limit": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "ad_account_spending_limit" }, "ad_account_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Null = no account spending limit." }, "spent": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Spend counted against the limit since it was last reset." }, "level": { "type": "string", "enum": [ "none", "ok", "near", "reached", "unknown" ], "description": "`near` from 80 % of the limit; at `reached` the network stops every ad in the account." } }, "required": [ "object", "ad_account_id", "network", "currency", "limit", "spent", "level" ], "additionalProperties": false, "description": "The ad account's own spending limit, read live from the network." }, { "type": "null" } ] } }, "required": [ "object", "ad_account_id", "action", "dry_run", "note", "spending_limit" ], "additionalProperties": false }, "example": { "object": "ad_account_spending_limit_action", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "action": "reset", "dry_run": false, "note": "New period started — spend against the limit is back at 0.", "spending_limit": { "object": "ad_account_spending_limit", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "network": "meta", "currency": "SEK", "limit": { "amount_minor": 5000000, "currency": "SEK" }, "spent": { "amount_minor": 0, "currency": "SEK" }, "level": "ok" } } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request. · `ad_network_unsupported` — This can't be done on this ad network from NorReach yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:limits", "x-norreach-action": "ads.limits", "x-norreach-phase": "D", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/ad-campaigns": { "get": { "operationId": "list_ad_campaigns", "summary": "List live ad campaigns", "description": "The campaigns in the workspace's connected ad accounts as the hourly sync last saw them: network, status (`active`, `paused`, `other`), whether one of Nora's launches made it (`from_norreach`, `launch_id`), its daily budget in minor units when it has one at campaign level, and whether NorReach can switch it on and off (`can_switch` — Meta today). Filter by `network` and `status`. There is no operation that makes, generates or searches ads — new ads come from a plan (POST /briefs), and Nora builds the launch.\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "network", "in": "query", "required": false, "description": "meta, tiktok, reddit or chatgpt.", "schema": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "paused", "other" ] } } ], "responses": { "200": { "description": "List live ad campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "object": { "type": "string", "const": "ad_campaign" }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "ad_account_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "other" ], "description": "`active`, `paused`, or `other` (in review, deleted, archived …)." }, "from_norreach": { "type": "boolean", "description": "Made by one of Nora's launches — only these can be switched back on from NorReach (within the plan's daily cap)." }, "launch_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "daily_budget": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "The campaign's daily budget, when it has one at campaign level." }, "can_switch": { "type": "boolean", "description": "Pause / resume work from NorReach for this network." } }, "required": [ "id", "object", "network", "ad_account_id", "name", "status", "from_norreach", "launch_id", "daily_budget", "can_switch" ], "additionalProperties": false, "description": "A live campaign in a connected ad account, as the hourly sync last saw it." } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "object": "ad_campaign", "network": "meta", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "name": "Nurses SE — leads", "status": "active", "from_norreach": true, "launch_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "daily_budget": null, "can_switch": true } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "D", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/ad-campaigns/{id}/pause": { "post": { "operationId": "pause_ad_campaign", "summary": "Pause a live ad campaign", "description": "Switches a live campaign off in the ad network now — the same core as the Pause button on Ads › Performance. Always allowed for owners, admins and managers, also while outreach is paused: stopping spend is never held back. Campaigns on the other ad networks are paused in the network's own ads manager (422 ad_network_unsupported). `dry_run=true` checks it and changes nothing. Fires ad_campaign.paused.\n\nRequires the `ads:spend` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:spend" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Pause a live ad campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_campaign_action" }, "campaign_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "pause", "resume" ] }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "changed": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "object", "campaign_id", "action", "dry_run", "status", "changed", "note" ], "additionalProperties": false }, "example": { "object": "ad_campaign_action", "campaign_id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "action": "pause", "dry_run": false, "status": "paused", "changed": true, "note": "Paused — it stops spending within a few minutes." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request. · `ad_network_unsupported` — This can't be done on this ad network from NorReach yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:spend", "x-norreach-action": "ads.spend", "x-norreach-phase": "D", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/ad-campaigns/{id}/resume": { "post": { "operationId": "resume_ad_campaign", "summary": "Switch a live ad campaign back on", "description": "Switches a paused campaign back on — it starts spending again. Only within the plan's rules: owners, admins and managers; refused while outreach is paused (409 outreach_paused); only a campaign one of Nora's launches made, and only when its daily budget (the campaign's, else its ad sets' together) is within that launch's daily cap (422 ad_switch_blocked with `reason`: not_from_norreach, over_cap, budget_unknown). A campaign made outside NorReach is switched on in the network's own ads manager. Other ad networks than Meta: 422 ad_network_unsupported. Idempotency-Key required; `dry_run=true` runs every check and changes nothing. Fires ad_campaign.resumed.\n\nRequires the `ads:spend` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:spend" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Switch a live ad campaign back on", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_campaign_action" }, "campaign_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "pause", "resume" ] }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "changed": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "object", "campaign_id", "action", "dry_run", "status", "changed", "note" ], "additionalProperties": false }, "example": { "object": "ad_campaign_action", "campaign_id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b", "action": "resume", "dry_run": false, "status": "active", "changed": true, "note": "Switched on — it spends within its budget again." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know. · `idempotency_key_required` — This operation needs an Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state. · `outreach_paused` — Outreach is paused for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request. · `ad_switch_blocked` — This campaign can't be switched back on from NorReach. · `ad_network_unsupported` — This can't be done on this ad network from NorReach yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:spend", "x-norreach-action": "ads.spend", "x-norreach-phase": "D", "x-norreach-idempotency": "required", "x-norreach-dry-run": true, "x-norreach-reaches-people": true } }, "/ad-launches": { "get": { "operationId": "list_ad_launches", "summary": "List ad launches", "description": "The ad launches Nora built from the workspace's plans, newest first: network, status (`ready` = waiting for a person's yes), budget in minor units, schedule, how many ad sets and ads publishing creates, and the plan it came from. Filter by `status` and `network`. There is no operation that makes, generates or searches ads — new ads come from a plan (POST /briefs), and Nora builds the launch.\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ] } }, { "name": "network", "in": "query", "required": false, "description": "meta, tiktok, reddit or chatgpt.", "schema": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] } } ], "responses": { "200": { "description": "List ad launches", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "object": { "type": "string", "const": "ad_launch" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "network_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ], "description": "draft → generating → ready → publishing → published (or failed). Only `ready` waits for a person's yes." }, "plan_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ], "description": "The plan whose cards Nora built this launch from." }, "ad_account_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "landing_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "type": "object", "properties": { "daily_per_ad_set": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Per ad set (ad group) per day. Editable with PATCH while draft, ready or failed." }, "daily_cap": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "The most the whole launch may spend per day (set by the plan). A budget above it is refused." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "daily", "lifetime" ] }, "amount": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] } }, "required": [ "kind", "amount" ], "additionalProperties": false }, { "type": "null" } ], "description": "A campaign-level budget, on networks that use one." } }, "required": [ "daily_per_ad_set", "daily_cap", "campaign" ], "additionalProperties": false }, "ad_sets": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ad sets (ad groups) publishing creates." }, "ads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ads publishing creates." }, "schedule": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "continuous", "range" ], "description": "continuous = runs until switched off; range = between start and end." }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD (range only)." }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD, or null for no end date." } }, "required": [ "mode", "start", "end" ], "additionalProperties": false, "description": "When the ads run once switched on." }, "published_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A plain sentence when something went wrong (details are in the app)." }, "created_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "network", "network_name", "status", "plan_id", "ad_account_id", "objective", "landing_url", "budget", "ad_sets", "ads", "schedule", "published_at", "problem", "created_at", "updated_at" ], "additionalProperties": false, "description": "An ad launch Nora built from a plan: what publishing would create, with its budget and schedule. Everything is created paused in the ad network." } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "object": "ad_launch", "name": "Nurses in Stockholm — lead ads", "network": "meta", "network_name": "Meta", "status": "ready", "plan_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "objective": "leads", "landing_url": "https://example-care.norreach.dev/nurses", "budget": { "daily_per_ad_set": { "amount_minor": 15000, "currency": "SEK" }, "daily_cap": { "amount_minor": 50000, "currency": "SEK" }, "campaign": null }, "ad_sets": 3, "ads": 6, "schedule": { "mode": "range", "start": "2026-11-10", "end": "2026-11-24" }, "published_at": null, "problem": null, "created_at": "2026-11-04T09:12:33.120Z", "updated_at": "2026-11-04T10:02:11.000Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know. · `invalid_cursor` — That cursor doesn't belong to this list.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/ad-launches/{id}": { "get": { "operationId": "get_ad_launch", "summary": "Get an ad launch", "description": "One ad launch: its status, budget (minor units), daily cap, schedule, landing page, what publishing creates and, when something went wrong, a plain sentence about it (the details are in the app).\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Get an ad launch", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "object": { "type": "string", "const": "ad_launch" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "network_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ], "description": "draft → generating → ready → publishing → published (or failed). Only `ready` waits for a person's yes." }, "plan_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ], "description": "The plan whose cards Nora built this launch from." }, "ad_account_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "landing_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "type": "object", "properties": { "daily_per_ad_set": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Per ad set (ad group) per day. Editable with PATCH while draft, ready or failed." }, "daily_cap": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "The most the whole launch may spend per day (set by the plan). A budget above it is refused." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "daily", "lifetime" ] }, "amount": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] } }, "required": [ "kind", "amount" ], "additionalProperties": false }, { "type": "null" } ], "description": "A campaign-level budget, on networks that use one." } }, "required": [ "daily_per_ad_set", "daily_cap", "campaign" ], "additionalProperties": false }, "ad_sets": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ad sets (ad groups) publishing creates." }, "ads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ads publishing creates." }, "schedule": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "continuous", "range" ], "description": "continuous = runs until switched off; range = between start and end." }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD (range only)." }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD, or null for no end date." } }, "required": [ "mode", "start", "end" ], "additionalProperties": false, "description": "When the ads run once switched on." }, "published_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A plain sentence when something went wrong (details are in the app)." }, "created_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "network", "network_name", "status", "plan_id", "ad_account_id", "objective", "landing_url", "budget", "ad_sets", "ads", "schedule", "published_at", "problem", "created_at", "updated_at" ], "additionalProperties": false, "description": "An ad launch Nora built from a plan: what publishing would create, with its budget and schedule. Everything is created paused in the ad network." }, "example": { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "object": "ad_launch", "name": "Nurses in Stockholm — lead ads", "network": "meta", "network_name": "Meta", "status": "ready", "plan_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "objective": "leads", "landing_url": "https://example-care.norreach.dev/nurses", "budget": { "daily_per_ad_set": { "amount_minor": 15000, "currency": "SEK" }, "daily_cap": { "amount_minor": 50000, "currency": "SEK" }, "campaign": null }, "ad_sets": 3, "ads": 6, "schedule": { "mode": "range", "start": "2026-11-10", "end": "2026-11-24" }, "published_at": null, "problem": null, "created_at": "2026-11-04T09:12:33.120Z", "updated_at": "2026-11-04T10:02:11.000Z" } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false }, "patch": { "operationId": "update_ad_launch", "summary": "Change an ad launch's budget, schedule or name", "description": "Changes ONLY the name, the daily budget per ad set (integer minor units in the ad account's currency; the whole launch must stay within its daily cap) and the schedule — through the app's own review save, while the launch is a draft, ready or failed (the name can change any time). Audiences, ads, words and pictures are Nora's: ask for changes in the plan. Budgets and schedules of launches on networks other than Meta publish as Nora prepared them (409). `dry_run=true` answers the launch as it would be and changes nothing. Owners, admins and managers.\n\nRequires the `ads:spend` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:spend" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The launch's name in NorReach.", "type": "string", "minLength": 1, "maxLength": 200 }, "daily_budget_per_ad_set": { "description": "The daily budget of each ad set, in the ad account's currency. Must keep the whole launch within its daily cap.", "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false }, "schedule": { "description": "continuous, or a range from `start` to `end` (null = no end).", "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "continuous" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "range" }, "start": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "YYYY-MM-DD." }, "end": { "default": null, "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "YYYY-MM-DD." }, { "type": "null" } ] } }, "required": [ "mode", "start" ], "additionalProperties": false } ] } }, "additionalProperties": false, "description": "Only the name, the per-ad-set daily budget and the schedule can change. Audiences, ads, words and pictures are Nora's — ask for changes in the plan." }, "example": { "daily_budget_per_ad_set": { "amount_minor": 12000, "currency": "SEK" }, "schedule": { "mode": "range", "start": "2026-11-10", "end": "2026-11-30" } } } } }, "responses": { "200": { "description": "Change an ad launch's budget, schedule or name", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "object": { "type": "string", "const": "ad_launch" }, "name": { "type": "string" }, "network": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, "network_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ], "description": "draft → generating → ready → publishing → published (or failed). Only `ready` waits for a person's yes." }, "plan_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ], "description": "The plan whose cards Nora built this launch from." }, "ad_account_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "landing_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "budget": { "type": "object", "properties": { "daily_per_ad_set": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "Per ad set (ad group) per day. Editable with PATCH while draft, ready or failed." }, "daily_cap": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "The most the whole launch may spend per day (set by the plan). A budget above it is refused." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "daily", "lifetime" ] }, "amount": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] } }, "required": [ "kind", "amount" ], "additionalProperties": false }, { "type": "null" } ], "description": "A campaign-level budget, on networks that use one." } }, "required": [ "daily_per_ad_set", "daily_cap", "campaign" ], "additionalProperties": false }, "ad_sets": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ad sets (ad groups) publishing creates." }, "ads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many ads publishing creates." }, "schedule": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "continuous", "range" ], "description": "continuous = runs until switched off; range = between start and end." }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD (range only)." }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD, or null for no end date." } }, "required": [ "mode", "start", "end" ], "additionalProperties": false, "description": "When the ads run once switched on." }, "published_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "problem": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A plain sentence when something went wrong (details are in the app)." }, "created_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ] } }, "required": [ "id", "object", "name", "network", "network_name", "status", "plan_id", "ad_account_id", "objective", "landing_url", "budget", "ad_sets", "ads", "schedule", "published_at", "problem", "created_at", "updated_at" ], "additionalProperties": false, "description": "An ad launch Nora built from a plan: what publishing would create, with its budget and schedule. Everything is created paused in the ad network." }, "example": { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "object": "ad_launch", "name": "Nurses in Stockholm — lead ads", "network": "meta", "network_name": "Meta", "status": "ready", "plan_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "ad_account_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "objective": "leads", "landing_url": "https://example-care.norreach.dev/nurses", "budget": { "daily_per_ad_set": { "amount_minor": 12000, "currency": "SEK" }, "daily_cap": { "amount_minor": 50000, "currency": "SEK" }, "campaign": null }, "ad_sets": 3, "ads": 6, "schedule": { "mode": "range", "start": "2026-11-10", "end": "2026-11-30" }, "published_at": null, "problem": null, "created_at": "2026-11-04T09:12:33.120Z", "updated_at": "2026-11-04T10:02:11.000Z" } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:spend", "x-norreach-action": "ads.spend", "x-norreach-phase": "C", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/ad-launches/{id}/discard": { "post": { "operationId": "discard_ad_launch", "summary": "Send an ad launch back to a draft", "description": "Says no to a launch that is ready to publish: it goes back to a draft under Ads › Launches and nothing is published. The same deciding core as the Approvals page's Skip, so the key also needs approvals:decide (403 insufficient_scope otherwise). Only a `ready` launch can be discarded (409). `dry_run=true` checks it and changes nothing.\n\nRequires the `ads:spend` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:spend" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Send an ad launch back to a draft", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_launch_action" }, "launch_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "publish", "discard" ] }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ], "description": "The launch's status now (or after it, on a dry run)." }, "note": { "type": "string" } }, "required": [ "object", "launch_id", "action", "dry_run", "status", "note" ], "additionalProperties": false, "description": "What publishing or discarding a launch did — or, on a dry run, would do." }, "example": { "object": "ad_launch_action", "launch_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "action": "discard", "dry_run": false, "status": "draft", "note": "Skipped — it stays as a draft under Ads › Launches." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:spend", "x-norreach-action": "ads.spend", "x-norreach-phase": "C", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/ad-launches/{id}/publish": { "post": { "operationId": "publish_ad_launch", "summary": "Publish an ad launch", "description": "Publishes a launch Nora built, as the key's creator — exactly as the app's Publish button: it needs the ads.spend role, outreach must not be paused (409 outreach_paused), the landing page must be live, the network must allow publishing from NorReach, the ad account must be connected and the launch must pass the network's own checks (422 ad_publish_blocked with a `reason`). Everything is created PAUSED in the ad network; nothing spends until it's switched on there. It then publishes in the background — follow it with GET /ad-launches/{id}. `dry_run=true` runs every check and changes nothing.\n\nRequires the `ads:spend` scope (reaches people, spends or publishes).", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:spend" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Publish an ad launch", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_launch_action" }, "launch_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "action": { "type": "string", "enum": [ "publish", "discard" ] }, "dry_run": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "generating", "ready", "publishing", "published", "failed" ], "description": "The launch's status now (or after it, on a dry run)." }, "note": { "type": "string" } }, "required": [ "object", "launch_id", "action", "dry_run", "status", "note" ], "additionalProperties": false, "description": "What publishing or discarding a launch did — or, on a dry run, would do." }, "example": { "object": "ad_launch_action", "launch_id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "action": "publish", "dry_run": false, "status": "publishing", "note": "Publishing — Nora is setting it up in the ad account, paused. Nothing spends until it's switched on." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know. · `idempotency_key_required` — This operation needs an Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `conflict` — That conflicts with the current state. · `outreach_paused` — Outreach is paused for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request. · `ad_publish_blocked` — This ad launch can't be published yet.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:spend", "x-norreach-action": "ads.spend", "x-norreach-phase": "C", "x-norreach-idempotency": "required", "x-norreach-dry-run": true, "x-norreach-reaches-people": true } }, "/ads/insights": { "get": { "operationId": "get_ad_insights", "summary": "Ad results", "description": "Spend, impressions, clicks, results, cost per result (CPA), conversion value and ROAS from the hourly syncs — the numbers the Ads › Performance page shows — by `day`, `campaign` or `network`, over `from`–`to` (default the last 30 days, at most 366). Money is integer minor units, one row per currency (amounts in different currencies are never added). Missing numbers are null, never 0; the last day or two may still change.\n\nRequires the `ads:read` scope.", "tags": [ "Ads" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "ads:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day (YYYY-MM-DD, default 29 days before `to`).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (YYYY-MM-DD, default today).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "default": "day", "type": "string", "enum": [ "day", "campaign", "network" ] } }, { "name": "network", "in": "query", "required": false, "description": "meta, tiktok, reddit or chatgpt.", "schema": { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] } }, { "name": "ad_account_id", "in": "query", "required": false, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Ad results", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_insights" }, "from": { "type": "string" }, "to": { "type": "string" }, "group_by": { "type": "string", "enum": [ "day", "campaign", "network" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "const": "ad_insight" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY-MM-DD (group_by=day)." }, "network": { "anyOf": [ { "type": "string", "enum": [ "meta", "tiktok", "reddit", "chatgpt" ] }, { "type": "null" } ], "description": "group_by=network or campaign." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "group_by=campaign. id is null for a campaign no longer in the ad account." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Every amount on the row is in this currency. Rows never add different currencies together." }, "spend": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] }, "impressions": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "clicks": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "results": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The goal conversions the network counted." }, "result_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What a result is (Leads, Purchases …)." }, "cost_per_result": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ], "description": "CPA: spend ÷ results." }, "conversion_value": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Return on ad spend: conversion value ÷ spend." }, "ctr": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Click-through rate in percent." } }, "required": [ "object", "date", "network", "campaign", "currency", "spend", "impressions", "clicks", "results", "result_type", "cost_per_result", "conversion_value", "roas", "ctr" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "spend": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] }, "results": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cost_per_result": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] }, "conversion_value": { "anyOf": [ { "type": "object", "properties": { "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (öre, cents)." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO-4217 code." } }, "required": [ "amount_minor", "currency" ], "additionalProperties": false, "description": "Money in integer minor units of the ad account's currency." }, { "type": "null" } ] }, "roas": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "currency", "spend", "results", "cost_per_result", "conversion_value", "roas" ], "additionalProperties": false }, "description": "One total per currency." }, "truncated": { "type": "boolean", "description": "More rows than one answer reads — narrow the range." } }, "required": [ "object", "from", "to", "group_by", "data", "totals", "truncated" ], "additionalProperties": false, "description": "Ad results from the hourly syncs (the numbers the Ads › Performance page shows). Missing numbers are null, never 0. Days near today may still change." }, "example": { "object": "ad_insights", "from": "2026-10-07", "to": "2026-11-05", "group_by": "network", "data": [ { "object": "ad_insight", "date": null, "network": "meta", "campaign": null, "currency": "SEK", "spend": { "amount_minor": 1254000, "currency": "SEK" }, "impressions": 182340, "clicks": 2911, "results": 64, "result_type": "Leads", "cost_per_result": { "amount_minor": 19594, "currency": "SEK" }, "conversion_value": null, "roas": null, "ctr": 1.5965 } ], "totals": [ { "currency": "SEK", "spend": { "amount_minor": 1254000, "currency": "SEK" }, "results": 64, "cost_per_result": { "amount_minor": 19594, "currency": "SEK" }, "conversion_value": null, "roas": null } ], "truncated": false } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "ads:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/analytics/calls": { "get": { "operationId": "get_call_analytics", "summary": "Get AI call analytics", "description": "AI calls: how many, how many reached a person (connect rate), time on the phone, meetings booked on them, outcomes by status, sentiment, how many met their goal, credits used, and calls per day. Optionally for one campaign (`campaign_id`; another workspace's is 404). Over `from`–`to` (YYYY-MM-DD, UTC; default the last 30 days, at most 366 days). Read-only.\n\nRequires the `analytics:read` scope.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day (YYYY-MM-DD, UTC; default 29 days before `to`).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (YYYY-MM-DD, UTC; default today).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only this campaign's calls.", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } } ], "responses": { "200": { "description": "Get AI call analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "call_analytics" }, "from": { "type": "string", "description": "First day (YYYY-MM-DD, UTC)." }, "to": { "type": "string", "description": "Last day (YYYY-MM-DD, UTC)." }, "campaign_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Calls that reached a person." }, "connect_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "0..1 (four decimals); null when there is nothing to divide by." }, "total_duration_seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "average_duration_seconds": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Over calls that lasted; null when none did." }, "meetings_booked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Meetings booked on these calls." }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "status", "count" ], "additionalProperties": false }, "description": "Calls per status, most first." }, "sentiment": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative", "unknown" ], "additionalProperties": false }, "success": { "type": "object", "properties": { "analyzed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "successful": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Calls whose goal was met." }, "rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "0..1 (four decimals); null when there is nothing to divide by." } }, "required": [ "analyzed", "successful", "rate" ], "additionalProperties": false }, "credits_used": { "type": "object", "properties": { "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Whole credits (rounded half away from zero)." }, "exact": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,2})?$", "description": "The exact amount as a decimal string — a per-minute charge can hold a fraction of a credit." } }, "required": [ "credits", "exact" ], "additionalProperties": false, "description": "An amount of credits." }, "by_day": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "calls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "date", "calls", "connected" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "true when a source held more rows than the people / per-day roll-ups read (10 000); the totals are exact counts either way." } }, "required": [ "object", "from", "to", "campaign_id", "total", "connected", "connect_rate", "total_duration_seconds", "average_duration_seconds", "meetings_booked", "outcomes", "sentiment", "success", "credits_used", "by_day", "truncated" ], "additionalProperties": false, "description": "AI calls over a range: connect rate, duration, outcomes, sentiment, goals met, credits, by day." }, "example": { "object": "call_analytics", "from": "2026-10-07", "to": "2026-11-05", "campaign_id": null, "total": 120, "connected": 46, "connect_rate": 0.3833, "total_duration_seconds": 9120, "average_duration_seconds": 152, "meetings_booked": 9, "outcomes": [ { "status": "completed", "count": 41 }, { "status": "no_answer", "count": 52 }, { "status": "voicemail", "count": 22 }, { "status": "transferred", "count": 5 } ], "sentiment": { "positive": 21, "neutral": 18, "negative": 7, "unknown": 74 }, "success": { "analyzed": 46, "successful": 19, "rate": 0.413 }, "credits_used": { "credits": 1824, "exact": "1824" }, "by_day": [ { "date": "2026-11-04", "calls": 12, "connected": 5 } ], "truncated": false } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "analytics:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/analytics/campaigns/{id}": { "get": { "operationId": "get_campaign_analytics", "summary": "Get one campaign's analytics", "description": "One campaign's (or automation's) numbers: where its contacts stand now (in progress, paused, completed, replied, meeting booked), and its messages sent, delivered, opened, clicked and replied to and its AI calls over the range. Over `from`–`to` (YYYY-MM-DD, UTC; default the last 30 days, at most 366 days). Another workspace's campaign is 404. Read-only.\n\nRequires the `analytics:read` scope.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An id (UUID).", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "from", "in": "query", "required": false, "description": "First day (YYYY-MM-DD, UTC; default 29 days before `to`).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (YYYY-MM-DD, UTC; default today).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Get one campaign's analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "campaign_analytics" }, "campaign_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "campaign", "automation" ] }, "status": { "type": "string" }, "from": { "type": "string", "description": "First day (YYYY-MM-DD, UTC)." }, "to": { "type": "string", "description": "Last day (YYYY-MM-DD, UTC)." }, "enrollments": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in_progress": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "paused": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "meetings_booked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "in_progress", "paused", "completed", "replied", "meetings_booked" ], "additionalProperties": false, "description": "Where the campaign's contacts stand now (not limited to the range)." }, "messages": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "delivered": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "opened": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clicked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "sent", "delivered", "opened", "clicked", "replies" ], "additionalProperties": false, "description": "Messages of this campaign in the range." }, "calls": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "total", "connected" ], "additionalProperties": false, "description": "AI calls of this campaign in the range." } }, "required": [ "object", "campaign_id", "name", "kind", "status", "from", "to", "enrollments", "messages", "calls" ], "additionalProperties": false, "description": "One campaign's (or automation's) numbers." }, "example": { "object": "campaign_analytics", "campaign_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Clinics — winter staffing", "kind": "campaign", "status": "active", "from": "2026-10-07", "to": "2026-11-05", "enrollments": { "total": 240, "in_progress": 150, "paused": 6, "completed": 60, "replied": 19, "meetings_booked": 5 }, "messages": { "sent": 610, "delivered": 598, "opened": 0, "clicked": 0, "replies": 22 }, "calls": { "total": 30, "connected": 11 } } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "analytics:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/analytics/channels": { "get": { "operationId": "get_channel_analytics", "summary": "Get analytics per channel", "description": "Per channel (email, SMS, WhatsApp, LinkedIn): messages sent, replies, the different people reached and who wrote back, and the reply rate (people who replied / people reached). Over `from`–`to` (YYYY-MM-DD, UTC; default the last 30 days, at most 366 days). Read-only.\n\nRequires the `analytics:read` scope.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day (YYYY-MM-DD, UTC; default 29 days before `to`).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (YYYY-MM-DD, UTC; default today).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Get analytics per channel", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "channel_analytics" }, "from": { "type": "string", "description": "First day (YYYY-MM-DD, UTC)." }, "to": { "type": "string", "description": "Last day (YYYY-MM-DD, UTC)." }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "sms", "whatsapp", "linkedin" ] }, "messages_sent": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Messages that went out (queued, sent, delivered, read)." }, "replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Messages that came in." }, "people_reached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Different people messages went out to." }, "people_replied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Different people who wrote back." }, "reply_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "people_replied / people_reached (0..1)." } }, "required": [ "channel", "messages_sent", "replies", "people_reached", "people_replied", "reply_rate" ], "additionalProperties": false } }, "truncated": { "type": "boolean", "description": "true when a source held more rows than the people / per-day roll-ups read (10 000); the totals are exact counts either way." } }, "required": [ "object", "from", "to", "channels", "truncated" ], "additionalProperties": false, "description": "Messages, replies and the people reached per channel (email, SMS, WhatsApp, LinkedIn)." }, "example": { "object": "channel_analytics", "from": "2026-10-07", "to": "2026-11-05", "channels": [ { "channel": "email", "messages_sent": 1500, "replies": 70, "people_reached": 520, "people_replied": 52, "reply_rate": 0.1 }, { "channel": "sms", "messages_sent": 210, "replies": 18, "people_reached": 90, "people_replied": 13, "reply_rate": 0.1444 }, { "channel": "whatsapp", "messages_sent": 80, "replies": 9, "people_reached": 30, "people_replied": 6, "reply_rate": 0.2 }, { "channel": "linkedin", "messages_sent": 40, "replies": 0, "people_reached": 0, "people_replied": 0, "reply_rate": null } ], "truncated": false } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "analytics:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/analytics/overview": { "get": { "operationId": "get_analytics_overview", "summary": "Get the analytics overview", "description": "The workspace's outreach at a glance: contacts added, messages sent and replies (and the different people behind them), AI calls and how many reached a person, meetings booked, and the campaigns running now. Over `from`–`to` (YYYY-MM-DD, UTC; default the last 30 days, at most 366 days). Read-only.\n\nRequires the `analytics:read` scope.", "tags": [ "Analytics" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "analytics:read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "First day (YYYY-MM-DD, UTC; default 29 days before `to`).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, { "name": "to", "in": "query", "required": false, "description": "Last day (YYYY-MM-DD, UTC; default today).", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } ], "responses": { "200": { "description": "Get the analytics overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "analytics_overview" }, "from": { "type": "string", "description": "First day (YYYY-MM-DD, UTC)." }, "to": { "type": "string", "description": "Last day (YYYY-MM-DD, UTC)." }, "contacts": { "type": "object", "properties": { "added": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Contacts created in the range." } }, "required": [ "added" ], "additionalProperties": false }, "messages": { "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replies": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "people_reached": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "people_replied": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reply_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "0..1 (four decimals); null when there is nothing to divide by." } }, "required": [ "sent", "replies", "people_reached", "people_replied", "reply_rate" ], "additionalProperties": false }, "calls": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connected": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Calls that reached a person." }, "connect_rate": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "0..1 (four decimals); null when there is nothing to divide by." } }, "required": [ "total", "connected", "connect_rate" ], "additionalProperties": false }, "meetings": { "type": "object", "properties": { "booked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Meetings booked in the range (from every source)." } }, "required": [ "booked" ], "additionalProperties": false }, "campaigns": { "type": "object", "properties": { "active": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Campaigns running now." } }, "required": [ "active" ], "additionalProperties": false }, "truncated": { "type": "boolean", "description": "true when a source held more rows than the people / per-day roll-ups read (10 000); the totals are exact counts either way." } }, "required": [ "object", "from", "to", "contacts", "messages", "calls", "meetings", "campaigns", "truncated" ], "additionalProperties": false, "description": "The workspace's outreach over a range: contacts added, messages and replies, AI calls, meetings booked." }, "example": { "object": "analytics_overview", "from": "2026-10-07", "to": "2026-11-05", "contacts": { "added": 214 }, "messages": { "sent": 1830, "replies": 97, "people_reached": 640, "people_replied": 71, "reply_rate": 0.1109 }, "calls": { "total": 120, "connected": 46, "connect_rate": 0.3833 }, "meetings": { "booked": 18 }, "campaigns": { "active": 4 }, "truncated": false } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "analytics:read", "x-norreach-action": null, "x-norreach-phase": "C", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/approvals": { "get": { "operationId": "list_approvals", "summary": "List what waits for approval", "description": "Everything in the workspace waiting for a person's yes — held messages and calls, plan cards, meetings to confirm, ad launches, landing pages — most urgent first, exactly as the Approvals page ranks it. Narrow it with `tab` or `kind`. The queue is a ranked snapshot, not a paged list: `has_more` says items beyond `limit` exist.\n\nRequires the `approvals:read` scope.", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:read" ] } ], "parameters": [ { "name": "tab", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "messages", "calls", "posts", "ads", "meetings" ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "run_gate", "sequence_send", "rule_send", "auto_reply", "plan_card", "meeting", "ad_launch", "landing_page", "api_call", "api_message", "number_buy" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "List what waits for approval", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "object": { "type": "string", "const": "approval" }, "kind": { "type": "string", "enum": [ "run_gate", "sequence_send", "rule_send", "auto_reply", "plan_card", "meeting", "ad_launch", "landing_page", "api_call", "api_message", "number_buy" ], "description": "What is waiting. `api_call` / `api_message` were requested through this API." }, "tab": { "type": "string", "enum": [ "messages", "calls", "posts", "ads", "meetings" ] }, "title": { "type": "string", "description": "Customer words, e.g. “Follow-up email to Anna Lindqvist”." }, "why": { "type": "string", "description": "Why it waits: the rule, the hold, the booking source." }, "source_label": { "type": "string", "description": "Where it came from (a campaign, the plan, an automation, the API)." }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "company" ], "additionalProperties": false }, { "type": "null" } ] }, "preview": { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {}, "description": "What would go out: an email, a message, a call, a post, an ad, a meeting, a page." }, "waiting_since": { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, "goes_out_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ], "description": "When it goes out once approved (or by itself, when `auto`)." }, "auto": { "type": "boolean", "description": "It goes out at `goes_out_at` by itself unless someone stops it." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people or rows the item stands for (a batch)." }, "risk": { "type": "string", "enum": [ "safe", "money", "voice", "external", "unverified_claim" ] }, "can": { "type": "object", "properties": { "approve": { "type": "boolean" }, "skip": { "type": "boolean" }, "redraft": { "type": "boolean", "description": "“Change it in words” works on it." }, "edit": { "anyOf": [ { "type": "string", "enum": [ "words", "meeting" ] }, { "type": "null" } ], "description": "What `edits` an approval may carry." }, "web_only": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when it can only be decided in the app (e.g. a claim to check)." } }, "required": [ "approve", "skip", "redraft", "edit", "web_only" ], "additionalProperties": false } }, "required": [ "key", "object", "kind", "tab", "title", "why", "source_label", "contact", "preview", "waiting_since", "goes_out_at", "auto", "count", "risk", "can" ], "additionalProperties": false, "description": "One item waiting for a person's yes." } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "object": "approval", "kind": "plan_card", "tab": "messages", "title": "Follow-up email to Anna Lindqvist", "why": "Your plan asks before it sends follow-ups.", "source_label": "Spring staffing plan", "contact": { "id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d", "name": "Anna Lindqvist", "company": "Example Care AB" }, "preview": { "kind": "email", "to": "Anna Lindqvist", "subject": "Nurses for the summer", "body": "Hi Anna, …" }, "waiting_since": "2026-11-04T09:12:33.120Z", "goes_out_at": "2026-11-05T08:30:00.000Z", "auto": false, "count": 1, "risk": "safe", "can": { "approve": true, "skip": true, "redraft": true, "edit": "words", "web_only": null } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:read", "x-norreach-action": null, "x-norreach-phase": "B", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/approvals/{key}": { "get": { "operationId": "get_approval", "summary": "One waiting item", "description": "One item of the queue by its key, with the preview of what would go out. 404 once it has been decided (here, in the app or by Nora).\n\nRequires the `approvals:read` scope.", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:read" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths).", "schema": { "type": "string", "minLength": 3, "maxLength": 200 } } ], "responses": { "200": { "description": "One waiting item", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "object": { "type": "string", "const": "approval" }, "kind": { "type": "string", "enum": [ "run_gate", "sequence_send", "rule_send", "auto_reply", "plan_card", "meeting", "ad_launch", "landing_page", "api_call", "api_message", "number_buy" ], "description": "What is waiting. `api_call` / `api_message` were requested through this API." }, "tab": { "type": "string", "enum": [ "messages", "calls", "posts", "ads", "meetings" ] }, "title": { "type": "string", "description": "Customer words, e.g. “Follow-up email to Anna Lindqvist”." }, "why": { "type": "string", "description": "Why it waits: the rule, the hold, the booking source." }, "source_label": { "type": "string", "description": "Where it came from (a campaign, the plan, an automation, the API)." }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "An id (UUID)." }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "company" ], "additionalProperties": false }, { "type": "null" } ] }, "preview": { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {}, "description": "What would go out: an email, a message, a call, a post, an ad, a meeting, a page." }, "waiting_since": { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, "goes_out_at": { "anyOf": [ { "type": "string", "description": "RFC 3339 UTC timestamp with milliseconds." }, { "type": "null" } ], "description": "When it goes out once approved (or by itself, when `auto`)." }, "auto": { "type": "boolean", "description": "It goes out at `goes_out_at` by itself unless someone stops it." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many people or rows the item stands for (a batch)." }, "risk": { "type": "string", "enum": [ "safe", "money", "voice", "external", "unverified_claim" ] }, "can": { "type": "object", "properties": { "approve": { "type": "boolean" }, "skip": { "type": "boolean" }, "redraft": { "type": "boolean", "description": "“Change it in words” works on it." }, "edit": { "anyOf": [ { "type": "string", "enum": [ "words", "meeting" ] }, { "type": "null" } ], "description": "What `edits` an approval may carry." }, "web_only": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when it can only be decided in the app (e.g. a claim to check)." } }, "required": [ "approve", "skip", "redraft", "edit", "web_only" ], "additionalProperties": false } }, "required": [ "key", "object", "kind", "tab", "title", "why", "source_label", "contact", "preview", "waiting_since", "goes_out_at", "auto", "count", "risk", "can" ], "additionalProperties": false, "description": "One item waiting for a person's yes." }, "example": { "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "object": "approval", "kind": "plan_card", "tab": "messages", "title": "Follow-up email to Anna Lindqvist", "why": "Your plan asks before it sends follow-ups.", "source_label": "Spring staffing plan", "contact": { "id": "7d1c3b2a-5e4f-4a1b-9c8d-0e1f2a3b4c5d", "name": "Anna Lindqvist", "company": "Example Care AB" }, "preview": { "kind": "email", "to": "Anna Lindqvist", "subject": "Nurses for the summer", "body": "Hi Anna, …" }, "waiting_since": "2026-11-04T09:12:33.120Z", "goes_out_at": "2026-11-05T08:30:00.000Z", "auto": false, "count": 1, "risk": "safe", "can": { "approve": true, "skip": true, "redraft": true, "edit": "words", "web_only": null } } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:read", "x-norreach-action": null, "x-norreach-phase": "B", "x-norreach-idempotency": "none", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/approvals/{key}/approve": { "post": { "operationId": "approve_approval", "summary": "Approve an item", "description": "Says yes as the key's creator — it goes out (or goes live) through the same checks as the Approvals page: the outreach pause, the creator's role, the item re-read in this workspace. Optional `edits` change the words (or a meeting's time, length, email or host) as it is approved. An ad launch also needs `ads:spend`, a landing page `pages:publish`, a plan card `plans:approve`. Already decided → 409 already_decided; a claim that needs checking → 409 conflict (decide it in the app). `dry_run=true` checks it still waits and changes nothing.\n\nRequires the `approvals:decide` scope (reaches people, spends or publishes).", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:decide" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths).", "schema": { "type": "string", "minLength": 3, "maxLength": 200 } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "edits": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 300 }, "body": { "description": "The edited words (email body, message text, a card's words).", "type": "string", "maxLength": 20000 }, "meeting": { "type": "object", "properties": { "starts_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "minutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "host_id": { "description": "Another member to host it (staff only).", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "force": { "description": "Approve even though the host's calendar shows a clash.", "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Edits approved together with the item." } }, "additionalProperties": false }, "example": { "edits": { "body": "Hi Anna, a shorter version …" } } } } }, "responses": { "200": { "description": "Approve an item", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "approval_decision" }, "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "decision": { "type": "string", "enum": [ "approve", "skip" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The item's status after the decision (approved, rejected, queued, scheduled …)." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows were decided (a batch: many; 0 when it was already decided the same way)." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What happened, in customer words." } }, "required": [ "object", "key", "decision", "status", "count", "note" ], "additionalProperties": false, "description": "A decision that went through." }, { "type": "object", "properties": { "object": { "type": "string", "const": "approval_decision" }, "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "decision": { "type": "string", "enum": [ "approve", "skip" ] }, "status": { "type": "string", "const": "dry_run" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "would": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "run_gate", "sequence_send", "rule_send", "auto_reply", "plan_card", "meeting", "ad_launch", "landing_page", "api_call", "api_message", "number_buy" ] }, "title": { "type": "string" } }, "required": [ "kind", "title" ], "additionalProperties": false } }, "required": [ "object", "key", "decision", "status", "count", "note", "would" ], "additionalProperties": false } ] }, "example": { "object": "approval_decision", "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "decision": "approve", "status": "approved", "count": 1, "note": "Approved — it goes out on schedule." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know. · `idempotency_key_required` — This operation needs an Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `already_decided` — Already handled. · `conflict` — That conflicts with the current state. · `outreach_paused` — Outreach is paused for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again. · `number_cap_reached` — The workspace's limit for buying numbers through the API is reached.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:decide", "x-norreach-action": "approvals.decide", "x-norreach-phase": "B", "x-norreach-idempotency": "required", "x-norreach-dry-run": true, "x-norreach-reaches-people": true } }, "/approvals/{key}/redraft": { "post": { "operationId": "redraft_approval", "summary": "Change an item in words", "description": "Nora rewrites a waiting message or card from a short instruction (“shorter”, “mention the site survey”). Nothing is sent — the item keeps waiting with the new words.\n\nRequires the `approvals:decide` scope (reaches people, spends or publishes).", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:decide" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths).", "schema": { "type": "string", "minLength": 3, "maxLength": 200 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 2, "maxLength": 600 } }, "required": [ "instruction" ], "additionalProperties": false }, "example": { "instruction": "Shorter, and mention the site survey." } } } }, "responses": { "200": { "description": "Change an item in words", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "redraft" }, "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "before": { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} }, "preview": { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} } }, "required": [ "object", "key", "before", "preview" ], "additionalProperties": false }, "example": { "object": "redraft", "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "before": { "kind": "email", "to": "Anna Lindqvist", "subject": "Nurses for the summer", "body": "Hi Anna, …" }, "preview": { "kind": "email", "to": "Anna Lindqvist", "subject": "Nurses for the summer", "body": "Hi Anna — short version …" } } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:decide", "x-norreach-action": "approvals.decide", "x-norreach-phase": "B", "x-norreach-idempotency": "optional", "x-norreach-dry-run": false, "x-norreach-reaches-people": false } }, "/approvals/{key}/skip": { "post": { "operationId": "skip_approval", "summary": "Skip an item", "description": "Says no: nothing goes out (a meeting is declined and the attendee hears; an ad launch or page goes back to a draft). Already decided → 409 already_decided.\n\nRequires the `approvals:decide` scope (reaches people, spends or publishes).", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:decide" ] } ], "parameters": [ { "name": "key", "in": "path", "required": true, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths).", "schema": { "type": "string", "minLength": 3, "maxLength": 200 } }, { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Skip an item", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "approval_decision" }, "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "decision": { "type": "string", "enum": [ "approve", "skip" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The item's status after the decision (approved, rejected, queued, scheduled …)." }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many rows were decided (a batch: many; 0 when it was already decided the same way)." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What happened, in customer words." } }, "required": [ "object", "key", "decision", "status", "count", "note" ], "additionalProperties": false, "description": "A decision that went through." }, { "type": "object", "properties": { "object": { "type": "string", "const": "approval_decision" }, "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "decision": { "type": "string", "enum": [ "approve", "skip" ] }, "status": { "type": "string", "const": "dry_run" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "would": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "run_gate", "sequence_send", "rule_send", "auto_reply", "plan_card", "meeting", "ad_launch", "landing_page", "api_call", "api_message", "number_buy" ] }, "title": { "type": "string" } }, "required": [ "kind", "title" ], "additionalProperties": false } }, "required": [ "object", "key", "decision", "status", "count", "note", "would" ], "additionalProperties": false } ] }, "example": { "object": "approval_decision", "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "decision": "skip", "status": "rejected", "count": 1, "note": "Skipped — nothing is sent." } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found` — That doesn't exist.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running. · `already_decided` — Already handled. · `conflict` — That conflicts with the current state. · `outreach_paused` — Outreach is paused for this workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again. · `number_cap_reached` — The workspace's limit for buying numbers through the API is reached.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:decide", "x-norreach-action": "approvals.decide", "x-norreach-phase": "B", "x-norreach-idempotency": "optional", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/approvals/decide": { "post": { "operationId": "decide_approvals", "summary": "Decide several items", "description": "Approves or skips up to 50 keys in one request, in order, one result each (`ok`, the status, or the `code` it would have answered alone). Each key goes through the same checks as deciding it alone; an approval of an ad launch, page or plan card without its own scope is refused for that key only.\n\nRequires the `approvals:decide` scope (reaches people, spends or publishes).", "tags": [ "Approvals" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "approvals:decide" ] } ], "parameters": [ { "name": "dry_run", "in": "query", "required": false, "description": "Run every check and return what would happen, changing nothing.", "schema": { "type": "boolean" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." } }, "decision": { "type": "string", "enum": [ "approve", "skip" ] } }, "required": [ "keys", "decision" ], "additionalProperties": false }, "example": { "keys": [ "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "meeting:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" ], "decision": "approve" } } } }, "responses": { "200": { "description": "Decide several items", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 3, "maxLength": 200, "description": "An approval key, e.g. `plan_card:`, `meeting:`, `rule_send:` (URL-encode the colon in paths)." }, "ok": { "type": "boolean" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When not ok: the problem code it would have answered alone." } }, "required": [ "key", "ok", "status", "count", "note", "code" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "const": false }, "next_cursor": { "type": "null" } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "key": "plan_card:5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "ok": true, "status": "approved", "count": 1, "note": "Approved.", "code": null } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "`bad_request` — The request couldn't be read. · `unknown_field` — The request has a field this operation doesn't know. · `idempotency_key_required` — This operation needs an Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`unauthorized` — A valid API key is required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope` — This API key doesn't have the scope this operation needs. · `feature_not_enabled` — The API isn't switched on for this workspace. · `role_forbidden` — The key's creator's role can't do this.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_in_progress` — A request with this Idempotency-Key is still running.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "`too_large` — The request body is too large.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed` — The request has invalid fields. · `idempotency_mismatch` — This Idempotency-Key was used with a different request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited` — Too many requests. Slow down and try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "`server_error` — Something went wrong on our side.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "`unavailable` — The API isn't available right now. Try again shortly.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-norreach-scope": "approvals:decide", "x-norreach-action": "approvals.decide", "x-norreach-phase": "B", "x-norreach-idempotency": "required", "x-norreach-dry-run": true, "x-norreach-reaches-people": false } }, "/audit-log": { "get": { "operationId": "list_audit_log", "summary": "List the audit log", "description": "The workspace's audit log, newest first: what happened, who did it, and — for anything done through the API — which key (or connected app), from REST or MCP, with the request id. Each entry names the ids it is about; its raw details are never served. Filter by `action` (exact, or a prefix like `contact.*`), `actor` (part of the name, e.g. an email or \"via API key\"), `since` / `until`. Owners and admins.\n\nRequires the `audit:read` scope.", "tags": [ "Audit log" ], "security": [ { "bearerAuth": [] }, { "oauth2": [ "audit:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–200, default 50).", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string", "maxLength": 512 } }, { "name": "action", "in": "query", "required": false, "description": "Only this action, or every action under a prefix (`contact.*`).", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,118}(?:\\.\\*)?$" } }, { "name": "actor", "in": "query", "required": false, "description": "Only entries whose actor contains this.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "since", "in": "query", "required": false, "description": "Only entries at or after this time (RFC 3339).", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "until", "in": "query", "required": false, "description": "Only entries before this time (RFC 3339).", "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } ], "responses": { "200": { "description": "List the audit log", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The entry's id." }, "object": { "type": "string", "const": "audit_entry" }, "action": { "type": "string", "description": "What happened (contact.erased, api.publish_page, Approved …)." }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who did it: a person's email, \" via API key