Tartol REST API reference

Available operations and access

REST accepts workspace-bound API keys. OAuth access tokens are issued for MCP and cannot authenticate REST requests. Active Pro and Agency workspaces can use REST. MCP is included with active Creator, Pro, and Agency plans. A valid connection whose workspace plan no longer qualifies receives 403; invalid, expired, revoked, unverified, or no-longer-authorized credentials receive 401.

The REST API and MCP share explicit external capability exclusions. Team and invitation administration, structural or cascading deletion, workspace settings, account-global notifications, and billing changes remain in the Tartol interface. Reading workspace members is available only with the relevant role permission. The OpenAPI document lists supported operations, and /api/v1/capabilities returns the subset available to your current key, role, and workspace.

Match the action schema

Read the live action schema before preparing or executing an operation. REST and MCP reject unknown fields, missing required fields, invalid nested options, and values of the wrong type. For example, send a numeric record ID as a JSON number, not a quoted string. REST returns 422 for invalid action arguments. Copy translation requires each language code and label to match an option returned by the action description.

Quickstart

The REST API is available to active Pro and Agency workspaces. Create an API key in Settings > Integrations and send it from a server, scheduled job, or secure backend.

Base URL: https://tartol.com/api/v1
Authorization: Bearer $TARTOL_API_KEY

Make your first request

curl "https://tartol.com/api/v1/ads?limit=3&sort=newest" \
  -H "Authorization: Bearer $TARTOL_API_KEY"

Authentication and scopes

Send the key in the Authorization header on every protected request. A key is limited to one workspace, its selected scopes, and the permissions of the user who created it. Revoking the key, removing workspace access, or losing plan access stops future requests.

Connection, discovery, and contracts

Ads, brands, and products

Product create/update schemas use the same standardized product-type and pricing-model enums as the Brands editor. Read the current enum values from the OpenAPI schema rather than sending free-form labels. Brand scans return the detected source language while the brand catalog summary is written in English for consistent review. Website scans read usable public HTML before using a rendered-page fallback, and recurring plan ranges are supported by explicit currency-and-cadence evidence from the complete selected page rather than a truncated content prefix.

Creative Studio, Brand Tracker, media, and workspace

Pagination and filters

List endpoints accept the controls documented for that endpoint. Discovery and Saved Ads support the full ad-filter set, including platform, advertiser, format, status, category, targeting, dates, duration, running days, and EU metrics. Unsupported parameters return 400.

• Discovery and Saved Ads return up to 60 records per page.
• Other paginated resources return up to 100 records per page unless their endpoint documents a lower limit.
• Pagination metadata includes page, limit, total when available, and has_more. Response links include self, previous, and next when applicable.

GET /api/v1/ads?status=active&format=video&running_days_min=7&eu_only=true&page=1&limit=12

Create and update resources

Use resource endpoints for normal application integrations. Every write requires JSON and an Idempotency-Key so a timeout can be retried safely. Generation requests return 202; use the returned generation ID with the matching status endpoint.

curl https://tartol.com/api/v1/brands \
  -X POST \
  -H "Authorization: Bearer $TARTOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-brand-2026-08-04-001" \
  --data '{"name":"Acme"}'

curl https://tartol.com/api/v1/generations/images \
  -X POST \
  -H "Authorization: Bearer $TARTOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-job-2026-08-04-001" \
  --data '{"productId":42,"numberOfImages":2,"generatePostText":false}'

curl https://tartol.com/api/v1/generations/images/123 \
  -H "Authorization: Bearer $TARTOL_API_KEY"

Use supported platform actions

Resource endpoints cover common integrations. The action API exposes additional supported external actions allowed by the key scopes and workspace role. The UI-only exclusions above still apply. Read an action’s live schema before sending it.

generate_product_audiences and generate_product_angles require an explicit count from 1 to 8. Tartol’s UI starts at 1, and each saved audience or angle costs 5 credits; the audience portrait is bundled into that price. Prepare responses include a structured credit_cost object so integrations can display the exact total before approval.

For advanced custom-audience Image Ads, read the product strategy, set autoAudience to false, and send only the saved selectedAudienceId. Avatar URLs and storage paths are display fields and must never be copied into generation arguments; Tartol validates the ID and resolves eligible casting evidence on the server.

1. 1List actionsCall GET /api/v1/actions.
2. 2Read the schemaCall GET /api/v1/actions/{actionType} for required fields, constraints, and an example.
3. 3ExecutePOST the arguments to /api/v1/actions/{actionType} with an Idempotency-Key.

curl https://tartol.com/api/v1/actions/create_brand \
  -X POST \
  -H "Authorization: Bearer $TARTOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-brand-2026-08-04-001" \
  --data '{"name":"Acme"}'

Optional confirm-first actions

Use the two-step flow when a person should review an action before it runs. It is required for credit-spending actions and consequential external actions such as publishing a saved Ad Manager draft to Meta. Prepared actions are short-lived, bound to the reviewed arguments, and can be used once.

Read and publish Ad Manager drafts

Read meta_ads_overview to receive token-free connection status, defaults, current plan allowance, saved drafts, and recent launch history. Its entitlement.adAccountsUsed is the shared publishing-account total across the subscriber’s active workspaces, with adAccountLimitScope set to account. The legacy adAccountsUsedThisMonth field reports monthly activity for the current workspace; it is not the ad-account quota. usedThisMonth still reports monthly ads published. Read meta_ads_performance for the selected ad account’s fixed 30-day KPI totals, daily series, and objective-aware ad rows. To publish, choose an exact saved draft and preserve both its draftId and draftUpdatedAt. Prepare launch_meta_ads_draft, show its exact paused-ad summary to a person, then execute the returned pending action after approval.

Programmatic publishing always forces every row to Paused and revalidates draft freshness, workspace ownership, plan limits, Meta assets, permissions, and idempotency. Meta OAuth, launch-default changes, campaign/ad-set creation, delivery status mutations, caller-selected report controls, provider import, caller-supplied unsaved rows, and Active delivery remain available only in the visual Ad Manager.

curl https://tartol.com/api/v1/views/meta_ads_overview \
  -H "Authorization: Bearer $TARTOL_API_KEY"

curl https://tartol.com/api/v1/actions/launch_meta_ads_draft/prepare \
  -X POST \
  -H "Authorization: Bearer $TARTOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: meta-draft-2026-08-14-001" \
  --data '{"draftId":"00000000-0000-4000-8000-000000000000","draftUpdatedAt":"2026-08-14T12:00:00.000Z"}'

curl https://tartol.com/api/v1/views/meta_ads_performance \
  -H "Authorization: Bearer $TARTOL_API_KEY"

Retry writes safely

Requests that execute a change require Idempotency-Key. Reusing the same key with the same request replays the stored response for 24 hours. Reusing it with different arguments returns 409.

• Generate a unique key for each intended change.
• Keep the same key when retrying a timeout.
• Do not reuse one key for multiple records or jobs.

Responses and errors

{
  "data": {},
  "meta": {},
  "links": {}
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "Provide a valid Tartol API key.",
    "requestId": "..."
  }
}

Limits and OpenAPI

Import the OpenAPI document into Postman, Insomnia, an SDK generator, or your developer portal. It includes resource routes, action routes, required headers, scopes, and error responses.

• Read requests: 600 per minute per API connection.
• Write requests: 120 per minute per API connection.
• Generation requests: 20 per minute per API connection.
• JSON request body: 256 KiB maximum.

https://tartol.com/api/v1/openapi.json