Infernet
Node
REST API

REST API Reference

The REST API enables two-fold functionality:

  1. It allows initiating and checking the status of off-chain Web2 compute requests
  2. It allows initiating on-chain Web3 requests via Delegate Subscriptions
ℹ️

The following examples assume an Infernet Node is running at localhost:4000.

Endpoints

1. GET /info

Retrieves information about the containers running on this node, and the number of jobs pending.

  • Method: GET
  • URL: /info
  • Response:
    • Success:
      • Code: 200 OK
      • Content:
        {
          "containers": Container[],
          "pending": {
            "offchain": integer,
            "onchain": integer
          }
        }
        • containers: Array of Container objects
        • pending: Job counts
          • offchain: Offchain jobs pending
          • onchain: Onchain jobs pending
      • Example:
        {
          "containers": [
            {
              "id": "ritualnetwork/infernet-llm-inference-0.1.0-mistral7b",
              "image": "ritualnetwork/infernet-llm-inference:0.1.0",
              "description": "Inference endpoint serving Mistral7B",
              "external": true
            }
          ],
          "pending": {
            "offchain": 5,
            "onchain": 3
          }
        }

2a. POST /api/jobs

Creates a new off-chain job (direct compute request or subscription).

  • Method: POST
  • URL: /api/jobs
  • Body: JobRequest
    • Example:
      curl -X POST http://localhost:4000/api/jobs \
        -H "Content-Type: application/json" \
        -d '{
          "containers": ["ritualnetwork/infernet-llm-inference-0.1.0-mistral7b"],
          "data": {
            "text": "Computer science is "
          }
        }'
  • Response:
    • Success:
      • Code: 200 OK
      • Content: { "id": string }
        • id: UUID of the created job.
      • Example:
        { "id": "1548865f-e806-41df-a756-f427c1d2e395" }
    • Failure:
      • Code: 400 Bad Request
      • Content: {"error": string[, "params": object]}
        • error: Error message
        • params: Additional error parameters (if applicable).
      • Example:
        {
          "error": "Container not supported",
          "params": {
            "container": "ritualnetwork/non-existent-container"
          }
        }

2b. POST /api/jobs/batch

Creates off-chain jobs in batch (direct compute requests or subscriptions).

NOTE: Individual job requests fail silently in batch mode, i.e. this endpoint might return 200 OK even if subset / all job requests fail. It is the caller's responsibility to check the returned array for errors in creating jobs.

  • Method: POST
  • URL: /api/jobs/batch
  • Body: JobRequest[]
    • Example:
      curl -X POST http://localhost:4000/api/jobs/batch \
        -H "Content-Type: application/json" \
        -d '[
          {
            "containers": ["ritualnetwork/infernet-llm-inference-0.1.0-mistral7b"],
            "data": {
              "text": "Computer science is "
            }
          },
          {
            "containers": ["ritualnetwork/infernet-llm-inference-0.1.0-mistral7b"],
            "data": {
              "text": "Material Science is "
            }
          },
          {
            "containers": ["ritualnetwork/non-existent-container"],
            "data": {
              "text": "Physics is "
            }
          }
        ]'
  • Response:
    • Success:
      • Code: 200 OK
      • Content: {"id": string} | {"error": string[, "params": object]} []
        • Array of job UUID or error for each JobRequest in order, depending on successful creation.
      • Example:
        [
          { "id": "1548865f-e806-41df-a756-f427c1d2e395" },
          { "id": "44d32839-fcd4-4129-a2bd-203541547e0c" },
          {
            "error": "Container not supported",
            "params": { "container": "ritualnetwork/non-existent-container" }
          }
        ]

3. GET /api/jobs

Retrieves specific job results based on one or more provided job IDs. If the id query parameter is not provided, returns a list of job IDs for the client. Optionally filters by pending status.

  • Method: GET

  • URL: /api/jobs

  • Query Parameters:

    • id (string, optional, repeatable): Job UUID(s). If provided, the endpoint returns the status of the specific job(s). Multiple job IDs can be specified by repeating this parameter (e.g., ?id=123&id=456). If omitted, the endpoint returns a list of job IDs for the given client.

    • intermediate (boolean, optional): Only used if id is provided. Flag for returning intermediate results. Applies to all specified jobs

    • pending (boolean, optional): Only used if id is omitted. Flag to specify whether to fetch pending (true), finished (false), or all jobs (omit).

    • Examples:

      # Get all job IDs
      curl http://localhost:4000/api/jobs
     
      # Get all pending job IDs
      curl http://localhost:4000/api/jobs?pending=true
     
      # Get all completed job IDs
      curl http://localhost:4000/api/jobs?pending=false
     
      # Get job output, including intermediate results
      curl "http://localhost:4000/api/jobs?id=1548865f-e806-41df-a756-f427c1d2e395&id=44d32839-fcd4-4129-a2bd-203541547e0c&intermediate=true"
  • Response:

    • Success:

      • Code: 200 OK

      • Content:

        • If id is provided: JobResult[]

          • If intermediate=true, includes intermediate results.
        • Examples:

          [
            {
              "id": "e280bbb0-04ab-4967-a998-b70692dfa3fd",
              "result": null,
              "status": "running"
            }
          ]
          [
            {
              "id": "e280bbb0-04ab-4967-a998-b70692dfa3fd",
              "result": {
                "container": "ritualnetwork/infernet-llm-inference-0.1.0-mistral7b",
                "error": "Invalid input"
              },
              "intermediate": [],
              "status": "failed"
            }
          ]
          [
            {
              "id": "3b0dc01e-1555-4ce4-8012-644f5e4c0dc7",
              "result": {
                "container": "ritualnetwork/infernet-llm-inference-0.1.0-mistral7b",
                "output": {
                  "completion": "a field that focuses on teaching people how to create software, design systems, and use computers to their fullest potential."
                }
              },
              "intermediate": [],
              "status": "success"
            }
          ]
        • If id is not provided: An array of job IDs (string[])

          • If pending=true, only returns pending jobs.
          • If pending=false, only returns finished jobs.
          • If pending is omitted, returns all jobs.
        • Example:

          [
            "b7a7f9a7-8f80-4905-96a9-c9c7d3ef83b8",
            "4ac0b5a5-eedb-4688-bb96-75afca891a47"
          ]

Data Types

JobRequest

Specifies a job, which consists of running one or more containers. If n containers are specified, output of container i is input to container i+1; containers[0] takes data as input; and containers[n-1]'s output is the result of the job.

  • containers (string[]) - Array of container IDs to run in sequence.
  • data (object) - The input data to be passed into containers[0].
{
    "containers": string[],
    "data": object
}

JobResult

{
    "id": string,
    "status": string,
    "result": ContainerResult,
    "intermediate_results": ContainerResult[]
}

Container

Represents a containerized workload running on the node.

  • id (string) - ID of the container.
  • external (boolean) - Whether the container is external, i.e. true if container can be the first container in JobRequest.
  • image (string) - The DockerHub image this container is running.
  • description (string, optional) - Description of the containerized workload.
{
  "id": string,
  "external": boolean,
  "image": string,
  "description": string
}

ContainerOutput

Represents the output data of a container.

  • container (string) - ID of the container.
  • output (object) - The output data, structure depends on the container.
{
  "container": string,
  "output": object
}

ContainerError

Represents the output error of a container.

  • container (string) - ID of the container.
  • error (string) - The error message from the container.
{
  "container": string,
  "error": string
}

ContainerResult

ContainerOutput or ContainerError.