Create an A2A task
const url = 'https://a2a.infiniteaudience.ai/a2a/tasks';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"skill":"discovery-count","messages":[{"role":"user","parts":[{"type":"text","text":"How many people aged 25–34 are in California?"}]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://a2a.infiniteaudience.ai/a2a/tasks \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "skill": "discovery-count", "messages": [ { "role": "user", "parts": [ { "type": "text", "text": "How many people aged 25–34 are in California?" } ] } ] }'Submits a new task to the Infinite Audience agent. Returns immediately with status “submitted”. Poll GET /a2a/tasks/{id} for progress.
The required scope depends on the requested skill (enforced per skill, mirroring the REST operations each skill fronts):
-
Requires ‘discovery’ scope:
discovery-count,discovery-lookup,match-history,delivery-history,delivery-status,catalog,pricing. -
Requires ‘purchase’ scope:
audience-management,segment-management,data-purchase,campaign-management,identity-resolution. -
Requires ‘account’ scope:
account-info,credit-purchase,subscription-management.
Tasks with a missing or unrecognised skill are rejected with 400 before any scope evaluation (fail closed).
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Agent-card skill id the task is submitted under — determines the required scope (see operation description). metadata.skill is accepted as a fallback for A2A clients that pass hints via metadata, but the top-level attribute is preferred.
One or more A2A message objects. Each message has a role (“user” or “agent”) and a parts array containing content fragments. Only the final user message is acted on; prior messages provide conversation context.
A message in an A2A task conversation.
object
Who authored this message.
One or more content fragments composing the message.
A single content fragment within an A2A message.
object
Content type. “text” for plain text, “data” for structured JSON.
The text content (present when type is “text”).
Structured JSON payload (present when type is “data”).
object
Optional caller-defined key/value pairs stored on the task.
object
Examples
Ask the agent to count an audience
{ "skill": "discovery-count", "messages": [ { "role": "user", "parts": [ { "type": "text", "text": "How many people aged 25–34 are in California?" } ] } ]}Multi-turn — provide additional context
{ "skill": "discovery-count", "messages": [ { "role": "user", "parts": [ { "type": "text", "text": "How many people aged 25–34 are in California?" } ] }, { "role": "agent", "parts": [ { "type": "text", "text": "I can help with that. Should I filter by any interests?" } ] }, { "role": "user", "parts": [ { "type": "text", "text": "Yes, filter by homeowners only." } ] } ]}Responses
Section titled “Responses”Task accepted — status is “submitted”.
object
Example
{ "id": "d3e4f5a6-7b8c-9d0e-1f2a-3b4c5d6e7f8a", "status": "submitted", "created_at": "2024-01-15T10:30:00Z"}Missing or unrecognised skill (must be one of the skill ids in the agent card — GET /.well-known/agent.json), or missing/empty messages array.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examplegenerated
{ "error": "example", "message": "example", "code": "example", "request_id": "example"}Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Unauthorized: Missing or invalid Authorization header"}{ "error": "Unauthorized", "code": "TOKEN_EXPIRED", "message": "Your session has expired. Please sign in again."}Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the purchase scope."}