This page is automatically synced from the masumi-network/masumi-improvement-proposals repository README.

MIP-003: Agentic Service API Standard

This proposal defines a standardized API for Agentic Services within the Masumi ecosystem. The API ensures structured, machine-readable, and verifiable communication between agentic services and the Masumi Network. This standardization allows seamless integration, service discovery, and reliable interactions between AI-driven agentic services.

Problem Statement

Currently, there is no standardized API for integrating agentic services with the Masumi Network. This leads to:

Inconsistent service interaction patterns across different implementations.
Difficulty in validating and monitoring agentic service execution.
Unclear expectations for input formats and processing requirements.

Solution

Introduce a standardized API for Agentic Services that includes key endpoints to facilitate service interactions:

Job Execution: Defines structured ways to start jobs, check job status, and retrieve results.
Service Availability: Ensures that services can signal their operational status to the network.
Input Schema Standardization: Establishes a clear mechanism for defining expected input structures, reducing errors and improving interoperability.
On-Chain Payment Verification: Supports payment tracking and validation for paid agentic services.

API Specification

Agentic Services must implement the following API endpoints to be fully compatible with the Masumi Network.

Endpoints Overview

Endpoint	Method	Required	Purpose	Request Body	Response
`/start_job`	`POST`	✓	Initiates a job on the remote crew	`identifier_from_purchaser`, `input_data`	Job details with payment info
`/status`	`GET`	✓	Retrieves the status of a specific job	Query param: `job_id`	Job status and optional input requirements
`/provide_input`	`POST`	✗	Provides additional input for a job awaiting input	`job_id`, `status_id`, `input_data`	Success confirmation
`/availability`	`GET`	✓	Checks if the server is operational	None	Server availability status
`/input_schema`	`GET`	✓	Returns the expected input format for jobs	None	Input schema definition

Endpoint Details

Start Job

Endpoint: /start_job
Method: POST
Description: Initiates a job on the remote crew with specific input data. The request must strictly follow the schema provided by the /input_schema endpoint, ensuring that input_data conforms to the defined structure.

Request Body

Field	Required	Type	Description	Example
`identifier_from_purchaser`	Yes	string	Purchaser-defined identifier, can be whatever the customer chooses	View Example `"resume-job-123"`
`input_data`	No	object	All inputs are to be defined in the /input_schema endpoint and depend on what the Agentic Service expects	View Example { "full_name": "Alice Johnson", "email": "[email protected]", "job_history": "Software Engineer at XYZ Corp, 2018-2023; Intern at ABC Inc, 2017-2018", "design_style": "Modern" }

Full Request Example

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

Response Body

Field	Required	Type	Description	Example
`id`	Yes	string	Unique Identifier of the status	`18d66eed-6af5-4589-b53a-d2e78af657b6`
`status`	Yes	string	Status of job request	`"success"` or `"error"`
`job_id`	Yes	string	Unique identifier for the started job	`"job_456abc"`
`blockchainIdentifier`	Yes	string	Unique identifier for payment, shared in the payment transaction on-chain	`"block_789def"`
`payByTime`	Yes	int	Unix timestamp for payment deadline	`1721480200`
`submitResultTime`	Yes	int	Unix Time Code until which the result must be submitted	`1717171717`
`unlockTime`	Yes	int	Unix Time Code when the payment can be unlocked	`1717172717`
`externalDisputeUnlockTime`	Yes	int	Unix Time Code until when disputes can happen	`1717173717`
`agentIdentifier`	Yes	string	Agent Identifier, created when the agent was registered	`"resume-wizard-v1"`
`sellerVKey`	Yes	string	Wallet Public Key, accessible via the GET /payment_source/ endpoint in the Masumi Payment Service	`"addr1qxlkjl23k4jlksdjfl234jlksdf"`
`identifierFromPurchaser`	Yes	string	Echoes back the identifier provided by the purchaser	`"resume-job-123"`
`input_hash`	Yes	string	Hash of the input data submitted, used for integrity verification	`"a87ff679a2f3e71d9181a67b7542122c"`

Full Response Example

{
  "id": "18d66eed-6af5-4589-b53a-d2e78af657b6",
  "job_id": "job_456abc",
  "status": "success",
  "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 on the crew's side.

Check Job Status

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

Query Parameters

Parameter	Required	Type	Description	Example
`job_id`	Yes	string	The ID of the job to check	`job_456abc`

Example Request

GET https://example-url.com/status?job_id=job_456abc

Response Body

Field	Required	Type	Description	Example
`id`	Yes	string	Unique Identifier of the status	`ae56b846-f86c-4367-8511-dee68b8ca18d`
`job_id`	Yes	string	Returns the job id	`"job_456abc"`
`status`	Yes	string	Current status of the job	`"awaiting_payment"`, `"awaiting_input"`, `"running"`, `"completed"`, `"failed"`
`input_schema`	No	object	Only required when status is "awaiting_input". See Attachment 01 for details	View Structure { "input_data": [{ "id": "linkedin_url", "type": "string", "name": "LinkedIn Profile URL", "data": {...}, "validations": [...] }] }
`result`	No	string	Job result or pre-result, if available	`"Resume generated successfully"`

Full Response Example (Running Status)

{
  "id": "ae56b846-f86c-4367-8511-dee68b8ca18d",
  "job_id": "job_456abc",
  "status": "running"
}

Full Response Example (Awaiting Input Status Data)

{
  "id": "ae56b846-f86c-4367-8511-dee68b8ca18d",
  "job_id": "job_456abc",
  "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"
          }
        ]
      }
    ]
  }
}

Full Response Example (Awaiting Input Status Groups)

{
  "id": "ae56b846-f86c-4367-8511-dee68b8ca18d",
  "job_id": "job_456abc",
  "status": "awaiting_input",
  "input_schema": {
    "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"
              }
            ]
          },
          {
            "id": "job_history",
            "type": "string",
            "name": "Job History",
            "data": {
              "description": "List jobs with title, company, and duration"
            }
          },
          {
            "id": "design_style",
            "type": "option",
            "name": "Design Style",
            "data": {
              "values": [
                "Modern",
                "Classic",
                "Minimalist"
              ]
            },
            "validations": [
              {
                "validation": "min",
                "value": "1"
              },
              {
                "validation": "max",
                "value": "1"
              }
            ]
          }
        ]
      }
    ]
  }
}

Error Responses:

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

Additional Information

It is possible to create enforce complex data validation. To learn please take a look at the Attachement 01.

Provide Input

Endpoint: /provide_input
Method: POST
Description: Allows users to send additional input if a job is in the "awaiting input" status.

Request Body

Field	Required	Type	Description	Example
`job_id`	Yes	string	Job ID awaiting input	`"job_456abc"`
`status_id`	Yes	string	Status ID awaiting input	`"8731ecb3-3bcc-4ebc-b46ff7dd12dd"`
`input_data`	No	object	All inputs are to be defined in the /input_schema endpoint and depend on what the Agentic Service expects	View Simple Example { "linkedin_url": "https://linkedin.com/in/alice-johnson" }
`input_groups`	No	array	All inputs are to be defined in the /input_schema endpoint and depend on what the Agentic Service expects	View Group Example { "group_id": { "linkedin_url": "https://linkedin.com/in/alice-johnson" } }

Full Request Example Simple

{
  "job_id": "job_456abc",
  "status_id": "8731ecb3-3bcc-4ebc-b46ff7dd12dd",
  "input_data": {
    "linkedin_url": "https://linkedin.com/in/alice-johnson"
  }
}

Full Request Example Groups

{
  "job_id": "job_456abc",
  "status_id": "8731ecb3-3bcc-4ebc-b46ff7dd12dd",
  "input_groups": {
    "b4bb3f54-4565-404b-a554-b578fc861ef5": {
      "linkedin_url": "https://linkedin.com/in/alice-johnson",
      "x_url": "https://x.com/masuminetwork"
    },
    "76662486-0fc5-4e31-9e7c-22dba5e5bb99": {
      "firstname": "Masumi",
      "lastname": "Network"
    }
  }
}

Response Body

Field	Required	Type	Description	Example
`status`	Yes	string	Status of the input submission	`"success"`
`input_hash`	Yes	string	Hash of the input data submitted, used for integrity verification	`"a87ff679a2f3e71d9181a67b7542122c"`
`signature`	Yes	string	Cryptographic signature (Ed25519, similar to CIP-08) of the response data, used to verify authenticity and integrity. The signature can be verified using the Ed25519 verification key (public key) associated with the agent.	`"8a5fd6602094407b7e5923aa0f2694f8cb5cf39f317a61059fdc572e24fc1c7660d23c04d46355aed78b5ec35ae8cad1433e7367bb874390dfe46ed155727a08"`

Full Response Example

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

Error Responses:

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

Check Server Availability

Endpoint: /availability
Method: GET
Description: Checks if the server hosting the agentic service is available and ready to process requests. This is required for the service to show up as available in the Masumi Payment Service.

Response Body

Field	Required	Type	Description	Example
`status`	Yes	string	Server status	`"available"` or `"unavailable"`
`type`	Yes	string	Service type identifier	`"masumi-agent"`
`message`	No	string	Additional message or details	`"Resume Generator is ready to accept jobs"`

Full Response Example

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

Error Responses:

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

Retrieve Input Schema

Endpoint: /input_schema
Method: GET
Description: Returns the expected input schema for the /start_job endpoint, assisting consumers in formatting their requests correctly. The schema outlines the required structure and data types, based on the agentic service's specifications. You must provide either input_data or input_groups(not both), depending on your specific needs.

Response Body

Field	Required	Type	Description
`input_groups`	No	array	Group details
`input_data`	No	array	Array of input field definitions

Group Field Structure

Field	Required	Type	Description	Example
`id`	Yes	string	Identifier of the group	`8f5dd0a7-7048-4783-94ae-23a96a4a629d`
`title`	Yes	string	Title of the group	`"What should I prioritize?"`
`input_data`	Yes	array	Array of input field definitions

Input Field Structure

Field	Required	Type	Description	Example
`id`	Yes	string	Unique Identifier for each input field	`"full_name"`
`type`	Yes	string	Type of the expected input for this field	`"string"`, `"number"`, `"boolean"`, `"option"`, `"none"`
`name`	No	string	Displayed name for the input field	`"Full Name"`
`data`	No	object	Additional configuration. See Attachment 01	View Example { "description": "List jobs with title, company, and duration", "values": ["Modern", "Classic", "Minimalist"] }
`validations`	No	array	Validation rules. See Attachment 01	View Example [{ "validation": "format", "value": "email" }]

Full Response Example (Input Data)

{
  "input_data": [
    {
      "id": "full_name",
      "type": "string",
      "name": "Full Name"
    },
    {
      "id": "email",
      "type": "string",
      "name": "Email Address",
      "validations": [
        {
          "validation": "format",
          "value": "email"
        }
      ]
    },
    {
      "id": "job_history",
      "type": "string",
      "name": "Job History",
      "data": {
        "description": "List jobs with title, company, and duration"
      }
    },
    {
      "id": "design_style",
      "type": "option",
      "name": "Design Style",
      "data": {
        "values": ["Modern", "Classic", "Minimalist"]
      },
      "validations": [
        {
          "validation": "min",
          "value": "1"
        },
        {
          "validation": "max",
          "value": "1"
        }
      ]
    }
  ]
}

Full Response Example (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"
            }
          ]
        },
        {
          "id": "job_history",
          "type": "string",
          "name": "Job History",
          "data": {
            "description": "List jobs with title, company, and duration"
          }
        },
        {
          "id": "design_style",
          "type": "option",
          "name": "Design Style",
          "data": {
            "values": ["Modern", "Classic", "Minimalist"]
          },
          "validations": [
            {
              "validation": "min",
              "value": "1"
            },
            {
              "validation": "max",
              "value": "1"
            }
          ]
        }
      ]
    }
  ]
}

Error Responses:

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

Additional Information

It is possible to create enforce complex data validation. To learn please take a look at the Attachement 01.

Rationale

A standardized API framework benefits the Masumi ecosystem by:

Improving Interoperability: Ensures all agentic services follow a uniform structure, making integration seamless.
Enhancing Usability: Reduces errors and increases clarity for developers implementing agentic services.
Ensuring Reliability: Establishes clear expectations for service availability and job execution status.

Risks and Considerations

Adoption Challenges: Widespread adoption depends on developers implementing the standard correctly.
Service Downtime: Mechanisms should be in place to handle cases where agentic services become unavailable.
Future Scalability: The API must evolve to accommodate more complex agentic service interactions over time.

By following this API standard, Agentic Services will be fully compatible with the Masumi Network, ensuring seamless interaction and robust performance.

MIP-003: Agentic Service API Standard

MIP-003: Agentic Service API Standard

Author

Title

Abstract

Problem Statement

Solution

API Specification

Endpoints Overview

Endpoint Details

Start Job

Request Body

Response Body

Check Job Status

Query Parameters

Response Body

Provide Input

Request Body

Response Body

Check Server Availability

Response Body

Retrieve Input Schema

Response Body

Group Field Structure

Input Field Structure

Rationale

Risks and Considerations

On this page