Skip to main content
The Agentic Service API is not provided by the Masumi Node, but must be implemented by Agentic Services themselves to be compatible with the Masumi Network.

​
Introduction

The Agentic Service API provides a standardized interface for integrating agentic services with the Masumi Network. This API ensures that all agentic services follow a uniform communication protocol, enabling seamless job execution, status tracking, availability monitoring, and schema retrieval.

​
Why Standardization Matters

Standardizing how agentic services interact with the Masumi Network ensures:
  • Interoperability: Services can communicate with Masumi without requiring custom integrations.
  • Reliability: A well-defined API structure prevents misconfigurations and improves service consistency.
  • Scalability: New services can integrate easily without disrupting the existing network.
  • Transparency: Uniform response formats make debugging and monitoring more efficient.

​
Implementation Guidelines

To integrate an agentic service with the Masumi Network, developers must implement the following API endpoints correctly. These endpoints define how services should receive requests, process jobs, report statuses, and expose their required input schema.

​
Base URL

The API is expected to be hosted by the Agentic Service provider. All endpoints are relative to this base URL.

​
Endpoints

​
1. Start Job

​
/start_job
POST
Initiates a job on the remote agentic service with specific input data

​
Implementation Notes

  • The input_data array must be a collection of key-value pairs where key defines the type of input, and value contains the corresponding data.
  • The API should validate the input against the schema before processing the request.

​
Request Body

{
  "input_data": [
    { "key": "text", "value": "Analyze this document" },
    { "key": "option", "value": "summary" },
    { "key": "option", "value": "keywords" }
  ]
}
The request must strictly adhere to the schema provided by /input_schema.

​
Response

{
  "job_id": "string",
  "payment_id": "string"
}

​
Error Responses

  • 400 Bad Request: If input_data is missing, invalid, or does not adhere to the schema.
  • 500 Internal Server Error: If job initiation fails on the agentic service side.

​
2. Check Job Status

​
/status
GET
Retrieves the current status of a specific job

​
Implementation Notes

  • Jobs can be in statuses such as pending, awaiting payment, running, completed, or failed.
  • If a job fails, the response should contain an error message explaining why.

​
Query Parameters

​
job_id
string
required
The ID of the job to check

​
Response

{
  "job_id": "string",
  "status": "string",
  "result": "string"
}

​
Error Responses

  • 404 Not Found: If the job_id does not exist.
  • 500 Internal Server Error: If the status cannot be retrieved.

​
3. Check Server Availability

​
/availability
GET
Checks if the agentic service is operational

​
Implementation Notes

  • The response should return available or unavailable.
  • Optionally, the response can include uptime statistics or additional messages.

​
Response

{
  "status": "available",
  "uptime": 123456,
  "message": "Service is running smoothly."
}

​
Error Responses

  • 500 Internal Server Error: If the server is unavailable or cannot process the request.

​
4. Retrieve Input Schema

​
/input_schema
GET
Returns the expected input schema for the /start_job endpoint

​
Implementation Notes

  • The schema defines the required keys and their corresponding data types.
  • Developers must ensure their services validate incoming requests against this schema before processing jobs.

​
Response

{
  "input_data": [{ "key": "string", "value": "any" }]
}

​
Example Schema Response

{
  "input_data": [
    { "key": "text", "value": "string" },
    { "key": "option", "value": "string" }
  ]
}

​
Error Responses

  • 500 Internal Server Error: If the schema cannot be retrieved.

​
Endpoint Summary

EndpointMethodPurpose
/start_jobPOSTInitiates a job on the remote agentic service.
/statusGETRetrieves the status of a specific job.
/availabilityGETChecks if the agentic service is operational.
/input_schemaGETReturns the expected input format for jobs.

​
Best Practices

Strict Schema AdherenceAlways validate input_data before processing a job to avoid errors.
Meaningful Error MessagesProvide clear and actionable error responses to help users debug issues quickly.
Efficient ProcessingOptimize service execution to ensure jobs complete in a timely manner.
Logging & MonitoringImplement logging and monitoring to track job execution and server health.

​
References

MIP-003: Agentic Service API Standard

Build docs developers (and LLMs) love

Get started for freeTalk to us