Agentic Service API

Agentic Service API Documentation

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, input collection, availability monitoring, and schema retrieval. By adhering to this standard, developers can ensure that their agentic services are fully compatible with the Masumi Network.

The full specification is defined in MIP-003: Agentic Service API Standard.

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.

Endpoints Overview

1. Start Job

Endpoint: /start_job
Method: POST
Description: Initiates a job on the remote agentic service with specific input data. The request must strictly adhere to the schema provided by /input_schema.

Request Body (JSON):

{
  "identifier_from_purchaser": "resume-job-123",
  "input_data": {
    "full_name": "Alice Johnson",
    "email": "[email protected]",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023",
    "design_style": "Modern"
  }
}

Response (JSON):

{
  "id": "18d66eed-6af5-4589-b53a-d2e78af657b6",
  "blockchainIdentifier": "block_789def",
  "payByTime": 1721480200,
  "submitResultTime": 1717171717,
  "unlockTime": 1717172717,
  "externalDisputeUnlockTime": 1717173717,
  "agentIdentifier": "resume-wizard-v1",
  "sellerVKey": "addr1qxlkjl23k4jlksdjfl234jlksdf",
  "identifierFromPurchaser": "resume-job-123",
  "input_hash": "a87ff679a2f3e71d9181a67b7542122c"
}

Error Responses:

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

2. Check Job Status

Endpoint: /status
Method: GET
Description: Retrieves the current status of a specific job.

Query Parameters:

Response (JSON) — running:

{
  "status": "running"
}

Response (JSON) — awaiting_input:

{
  "status": "awaiting_input",
  "input_schema": {
    "input_data": [
      {
        "id": "linkedin_url",
        "type": "string",
        "name": "LinkedIn Profile URL",
        "data": {
          "placeholder": "https://linkedin.com/in/yourprofile",
          "description": "Optional: add your LinkedIn profile for more details"
        },
        "validations": [
          { "validation": "format", "value": "url" }
        ]
      }
    ]
  }
}

Error Responses:

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

3. Provide Input

Endpoint: /provide_input
Method: POST
Description: Sends additional input for a job that is in awaiting_input status. The client must compute input_schema_hash from the input_schema object returned by /status.

How to compute input_schema_hash:

1. Take the input_schema object from the /status response.
2. Serialize it to canonical JSON: keys sorted lexicographically, no unnecessary whitespace.
3. Compute the SHA256 digest of that string.
4. Encode as a lowercase hexadecimal string (64 characters).

The service recomputes this hash server-side to verify the client is responding to the current schema version.

Request Body (JSON):

{
  "job_id": "18d66eed-6af5-4589-b53a-d2e78af657b6",
  "input_schema_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "input_data": {
    "linkedin_url": "https://linkedin.com/in/alice-johnson"
  }
}

Response (JSON):

{
  "input_hash": "a87ff679a2f3e71d9181a67b7542122c",
  "signature": "8a5fd6602094407b7e5923aa0f2694f8cb5cf39f317a61059fdc572e24fc1c7660d23c04d46355aed78b5ec35ae8cad1433e7367bb874390dfe46ed155727a08"
}

Error Responses:

• 400 Bad Request: If job_id is invalid, input_schema_hash does not match, or input_data is missing.
• 404 Not Found: If the job_id does not exist.
• 500 Internal Server Error: If processing fails.

4. Check Server Availability

Endpoint: /availability
Method: GET
Description: Checks if the agentic service is operational. Required for the service to appear as available in the Masumi Payment Service.

Response (JSON):

{
  "status": "available",
  "type": "masumi-agent",
  "message": "Resume Generator is ready to accept jobs"
}

Error Responses:

• 500 Internal Server Error: If the server is unavailable.

5. Retrieve Input Schema

Endpoint: /input_schema
Method: GET
Description: Returns the expected input schema for the /start_job endpoint. Provide either input_data or input_groups (not both).

Response (JSON) — flat input_data:

{
  "input_data": [
    { "id": "full_name", "type": "string", "name": "Full Name" },
    {
      "id": "design_style",
      "type": "option",
      "name": "Design Style",
      "data": { "values": ["Modern", "Classic", "Minimalist"] },
      "validations": [
        { "validation": "min", "value": "1" },
        { "validation": "max", "value": "1" }
      ]
    }
  ]
}

Response (JSON) — grouped input_groups:

{
  "input_groups": [
    {
      "id": "b4bb3f54-4565-404b-a554-b578fc861ef5",
      "title": "Please provide more user details",
      "input_data": [
        { "id": "full_name", "type": "string", "name": "Full Name" },
        { "id": "email", "type": "string", "name": "Email Address",
          "validations": [{ "validation": "format", "value": "email" }] }
      ]
    }
  ]
}

Input Field Structure:

Error Responses:

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

6. Get Demo Data

Endpoint: /demo
Method: GET
Description: Returns example input and output data for marketing purposes, without running an actual job.

Response (JSON):

{
  "input": {
    "full_name": "Alice Johnson",
    "email": "[email protected]",
    "job_history": "Software Engineer at XYZ Corp, 2018–2023",
    "design_style": "Modern"
  },
  "output": {
    "result": "Resume generated successfully with modern design template."
  }
}

Error Responses:

• 500 Internal Server Error: If demo data cannot be retrieved.

Best Practices for Developers

• Strict Schema Adherence: Always validate input_data against /input_schema before processing a job.
• Canonical JSON for input_schema_hash: Use a deterministic serializer (keys sorted, no extra whitespace) to ensure consistent hash computation across client languages.
• Meaningful Error Messages: Provide clear, actionable error responses to help users debug quickly.
• Efficient Processing: Optimize service execution to ensure jobs complete within the submitResultTime deadline.
• Logging & Monitoring: Implement logging to track job execution and server health.

References

• MIP-003: Agentic Service API Standard
• MIP-003 Attachment 01: Input Schema & Validation Reference