All methods are called via POST to https://www.magisterium.com/api/v1/a2a using JSON-RPC 2.0. Every request must include Authorization: Bearer $MAGISTERIUM_TOKEN (an OAuth-issued user token — see Authentication) and Content-Type: application/json.

Methods

message/send

Send a message to a skill and receive a completed task. All Magisterium skills are synchronous — the response contains the terminal task state (completed or failed), never an intermediate working status.

Params:

Field	Type	Required	Description
message	Message	Yes	The user message with parts and optional metadata.
message.role	string	Yes	Must be "user".
message.messageId	string	Yes	Unique ID for this message.
message.kind	string	Yes	Must be "message".
message.parts	Part[]	Yes	At least one part (text or data).
message.metadata.skillId	string	No	Skill to invoke. Defaults to catholic_qa.
message.contextId	string	No	Optional context ID for grouping related tasks. If omitted, the server generates one.
configuration	object	No	Reserved for future use.

Returns: A Task object with kind: "task".

tasks/get

Retrieve a previously created task by its ID.

Params:

Field	Type	Required	Description
id	string	Yes	The task ID returned from message/send.

Returns: The Task object, or a TASK_NOT_FOUND error if expired or missing. Tasks are stored for 24 hours.

tasks/cancel

Cancel a task if it is in a cancelable state. Because all skills resolve synchronously, most tasks are already in a terminal state (completed / failed) by the time the response returns — attempting to cancel a terminal task returns INVALID_PARAMS with an Invalid state transition message.

Params:

Field	Type	Required	Description
id	string	Yes	The task ID to cancel.

Returns: The updated Task object with status.state: "canceled".

Task Lifecycle

Magisterium's skills run synchronously, so a task is persisted to storage only after the skill finishes — always in a terminal state. The submitted and working states are part of the broader A2A specification but are never produced by Magisterium's implementation; you will only ever observe one of the three terminal states below.

State	Meaning
completed	Terminal — results are in artifacts. Returned by message/send when the skill finishes successfully.
failed	Terminal — status.message contains the failure reason. Returned by message/send when the skill throws.
canceled	Terminal — only reachable by calling tasks/cancel on a non-terminal task. Because tasks are already terminal by the time message/send returns, in practice cancelation is rejected with INVALID_PARAMS for any task you have a handle on.

Every task also carries:

• contextId — a grouping identifier you can reuse across follow-up messages to link related tasks.
• history — the ordered list of user and agent messages that produced the task's artifacts.

Error Codes

Code	Name	Description
-32700	Parse error	Invalid JSON body.
-32600	Invalid request	Missing jsonrpc, method, or id fields.
-32601	Method not found	Unknown JSON-RPC method.
-32602	Invalid params	Missing or invalid parameters (also returned for invalid tasks/cancel state transitions).
-32603	Internal error	Unexpected server-side failure.
-32001	Task not found	Task ID does not exist or has expired.
-32002	Skill not found	Unknown skillId in message metadata.
-32003	Rate limit exceeded	Too many requests. Check retryAfter (seconds) in the error data.
-32004	Unauthorized	Missing or invalid Bearer token.
-32005	Paid plan required	A2A requires a Pro, Organization, or Enterprise plan.

The HTTP status mirrors the error class: 401 for UNAUTHORIZED, 403 for PLAN_REQUIRED, 429 for RATE_LIMITED, and 200 for all other JSON-RPC errors (per the JSON-RPC convention of returning 200 with an error body).

Rate Limits

A2A shares the same rate-limit pool as MCP — see MCP Pricing for per-plan request caps.

Two variants are enforced:

• Default — applies to document_search, document_fetch, liturgical_readings, and saints_of_the_day.
• Expensive — applies to catholic_qa only, because it runs an LLM-backed answer pipeline. This variant uses a stricter, lower cap.

When you hit a limit, the error data object contains retryAfter in seconds. Callers should back off for that interval before retrying.

CORS

The endpoint responds to OPTIONS preflight requests and returns permissive CORS headers (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), so A2A can be called from browser-based orchestrators without a proxy.