tools/list for MCP clients.
HTTP is useful for scheduled jobs, backend services, and applications that
choose an operation in code rather than through model tool discovery.
The V3 REST API is available to authenticated Buyer and Seller accounts. Its
OpenAPI 3.1 document is available at
https://api.apostra.com/api/v3/openapi-3.1.yaml.search(kind: "creative") requires filter to contain exactly one of
advertiserId or campaignId. The MCP/runtime parser rejects both owners but
permits neither so a Seller can receive the contextual
OWN_SUPPLY_SCOPE_REQUIRED guidance. An ownerless Creative search is therefore
valid at the MCP parser boundary and invalid at the HTTP boundary.
Make a request
Send an API key or M2M access token as a bearer credential. The JSON request body is the operation input.X-SCOPE3-CUSTOMER-ID when the credential already resolves to one
account. Supplying the header never expands the credential’s account access.
Retry a write
Send anIdempotency-Key header with every V3 HTTP write request. Use the same
key and the same validated body to retry after a lost response. For seven days
after a write settles, that retry replays the typed result; changing the body
with the same key returns 409 CONFLICT. After seven days the completed receipt
and result are removed, and the key may name a new write. Do not reuse it unless
that new write is intentional.
An in-flight or uncertain receipt does not expire. Retry the same operation,
key, and body to receive 202 Accepted and Retry-After while recovery
continues. Do not mint a new key for an uncertain receipt.
Some operations also accept idempotencyKey in their JSON body. When that
field is present, it must exactly match Idempotency-Key; the API never uses
two different keys for one write.
For save_billing, paymentAuthority.action: "status" is a read-only poll.
It requires interchange:read, an exact credential-to-organization match, and
no advertiser scope. It returns status and expiry, never card details or the
capture-link URL. A child-bound credential cannot use inherited parent billing
access. Requesting or confirming payment authority remains an
interchange:write operation. See Authentication
for the member and inherited-account rules.
Handle the response
A successful call returns the operation’s typed result indata:
error:
content, _meta, or isError fields. Use
the status code for transport handling and the error code for recovery.
Unexpected server failures use a scrubbed INTERNAL_ERROR message.
Each HTTP operation has a 210-second route deadline, below the REST transport’s
240-second limit. A write can return 503 SERVICE_UNAVAILABLE only before the
API durably claims its receipt and before dispatch starts. Once claimed, a
deadline or closed connection leaves the receipt in flight or uncertain; a
connected caller receives 202 Accepted and Retry-After, while the API keeps
settling a completed dispatch in the background. The route does not try to
send a response to a closed socket.
Generate a client
The generated OpenAPI 3.1 document is available at:422 error when the request is structurally valid but cannot be applied.
The OpenAPI document does not claim that client construction proves those
business rules.
The existing /api/v3/openapi.yaml document remains the OpenAPI 3.0 contract
for the two v3 document resources. Integrations that need the fixed operation
routes must use the versioned OpenAPI 3.1 URL above.
The v2 API remains supported. Existing integrations do not need to migrate,
and APIs outside the public v3 operation catalogue continue to use v2.