Alle methoden worden aangeroepen via POST naar https://www.magisterium.com/api/v1/a2a met JSON-RPC 2.0. Elk verzoek moet Authorization: Bearer $MAGISTERIUM_TOKEN (een via OAuth uitgegeven gebruikerstoken — zie Authenticatie) en Content-Type: application/json bevatten.

Methoden

message/send

Stuur een bericht naar een skill en ontvang een voltooide taak. Alle Magisterium-skills zijn synchroon — de respons bevat de eindtoestand van de taak (completed of failed), nooit een tussentijdse working-status.

Parameters:

Veld	Type	Verplicht	Beschrijving
message	Message	Ja	Het gebruikersbericht met parts en optionele metadata.
message.role	string	Ja	Moet "user" zijn.
message.messageId	string	Ja	Unieke ID voor dit bericht.
message.kind	string	Ja	Moet "message" zijn.
message.parts	Part[]	Ja	Ten minste één part (text of data).
message.metadata.skillId	string	Nee	Aan te roepen skill. Standaard catholic_qa.
message.contextId	string	Nee	Optionele context-ID voor het groeperen van gerelateerde taken. Als deze wordt weggelaten, genereert de server er een.
configuration	object	Nee	Gereserveerd voor toekomstig gebruik.

Retourneert: Een Task-object met kind: "task".

tasks/get

Haal een eerder aangemaakte taak op aan de hand van zijn ID.

Parameters:

Veld	Type	Verplicht	Beschrijving
id	string	Ja	De taak-ID teruggegeven door message/send.

Retourneert: Het Task-object, of een TASK_NOT_FOUND fout als het is verlopen of ontbreekt. Taken worden 24 uur bewaard.

tasks/cancel

Annuleer een taak als deze zich in een annuleerbare toestand bevindt. Omdat alle skills synchroon worden afgehandeld, bevinden de meeste taken zich al in een eindtoestand (completed / failed) tegen de tijd dat de respons terugkomt — een poging tot annuleren van een taak in eindtoestand geeft INVALID_PARAMS terug met de melding Invalid state transition.

Parameters:

Veld	Type	Verplicht	Beschrijving
id	string	Ja	De te annuleren taak-ID.

Retourneert: Het bijgewerkte Task-object met status.state: "canceled".

Taaklevenscyclus

De skills van Magisterium draaien synchroon, dus een taak wordt pas naar opslag gepersisteerd nadat de skill is voltooid — altijd in een eindtoestand. De toestanden submitted en working maken deel uit van de bredere A2A-specificatie, maar worden door de implementatie van Magisterium nooit geproduceerd; u zult altijd slechts een van de drie onderstaande eindtoestanden waarnemen.

Toestand	Betekenis
completed	Eindtoestand — resultaten staan in artifacts. Wordt teruggegeven door message/send wanneer de skill succesvol wordt voltooid.
failed	Eindtoestand — status.message bevat de faalreden. Wordt teruggegeven door message/send wanneer de skill een fout gooit.
canceled	Eindtoestand — alleen bereikbaar door tasks/cancel aan te roepen op een taak in een niet-eindtoestand. Omdat taken al in een eindtoestand verkeren tegen de tijd dat message/send terugkeert, wordt annulering in de praktijk afgewezen met INVALID_PARAMS voor elke taak waarvan u een handle hebt.

Elke taak draagt bovendien:

• contextId — een groeperingsidentificatie die u opnieuw kunt gebruiken in vervolgberichten om gerelateerde taken te koppelen.
• history — de geordende lijst van gebruikers- en agentberichten die de artefacten van de taak hebben voortgebracht.

Foutcodes

Code	Naam	Beschrijving
-32700	Parse error	Ongeldige JSON-body.
-32600	Invalid request	Ontbrekende velden jsonrpc, method of id.
-32601	Method not found	Onbekende JSON-RPC-methode.
-32602	Invalid params	Ontbrekende of ongeldige parameters (ook teruggegeven voor ongeldige tasks/cancel-toestandsovergangen).
-32603	Internal error	Onverwachte fout aan serverzijde.
-32001	Task not found	Taak-ID bestaat niet of is verlopen.
-32002	Skill not found	Onbekende skillId in de berichtmetadata.
-32003	Rate limit exceeded	Te veel verzoeken. Controleer retryAfter (seconden) in het foutveld data.
-32004	Unauthorized	Ontbrekende of ongeldige Bearer-token.
-32005	Paid plan required	A2A vereist een Pro-, Organisatie- of Enterprise-plan.

De HTTP-status weerspiegelt de foutklasse: 401 voor UNAUTHORIZED, 403 voor PLAN_REQUIRED, 429 voor RATE_LIMITED, en 200 voor alle andere JSON-RPC-fouten (volgens de JSON-RPC-conventie om 200 met een error-body terug te geven).

Rate-limieten

A2A deelt dezelfde rate-limit-pool als MCP — zie MCP-prijzen voor de verzoekcaps per plan.

Twee varianten worden gehandhaafd:

• Default — geldt voor document_search, document_fetch, liturgical_readings en saints_of_the_day.
• Expensive — geldt alleen voor catholic_qa, omdat die een LLM-ondersteunde antwoordpipeline uitvoert. Deze variant gebruikt een strengere, lagere limiet.

Wanneer u een limiet bereikt, bevat het foutveld data de retryAfter in seconden. Aanroepers moeten voor dit interval terugtreden voordat ze het opnieuw proberen.

CORS

Het eindpunt reageert op OPTIONS-preflight-verzoeken en geeft permissieve CORS-headers terug (Access-Control-Allow-Origin: *, Allow-Methods: POST, OPTIONS, Allow-Headers: Content-Type, Authorization), zodat A2A vanuit op browsers gebaseerde orkestrators kan worden aangeroepen zonder proxy.