REST API Reference

The REST API enables two-fold functionality:

It allows initiating and checking the status of off-chain Web2 compute requests
It allows initiating on-chain Web3 requests via a Delegated Subscription

ℹ️

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": "openai-inference",
      "image": "ritualnetwork/css_inference_service:latest",
      "description": "OPENAI Inference Service",
      "external": true
    }
  ],
  "pending": {
    "offchain": 5,
    "onchain": 3
  }
}

2a. POST `/api/jobs`

Creates a new off-chain job. Direct compute requests (JobRequest) deliver results via REST endpoint, while delegated subscriptions (DelegatedSubscriptionRequest) deliver results on-chain (see reference (opens in a new tab) for details).

Method: POST
URL: /api/jobs

Body: JobRequest or DelegatedSubscriptionRequest

Creates a new direct compute request.

  curl -X POST http://localhost:4000/api/jobs \
    -H "Content-Type: application/json" \
    -d '{
      "containers": ["openai-completions"],
      "data": {
        "model": "gpt-3.5-turbo-16k",
        "params": {
          "endpoint": "completion"
          "messages": [{"role": "user", "content": "how do I make pizza?"}]
        }
      }
    }'

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": "non-existent-container"
  }
}
```

2b. POST `/api/jobs/batch`

Creates direct compute (JobRequest) and / or delegated subscriptions (DelegatedSubscriptionRequest) in batch.

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 / the chain for errors in creating jobs.

Method: POST
URL: /api/jobs/batch
Body: (JobRequest | DelegatedSubscriptionRequest)[]
- Array of JobRequests and / or DelegatedSubscriptionRequests (see /api/jobs for examples)

Response:

Success:

Code: 200 OK

Content: {"id": string} | {} | {"error": string[, "params": object]} []

Array of job UUIDs, empty objects, or errors in order for each JobRequest / DelegatedSubscriptionRequest, depending on successful creation.

Example:

[
  { "id": "1548865f-e806-41df-a756-f427c1d2e395" }, # Successful JobRequest
  { "id": "44d32839-fcd4-4129-a2bd-203541547e0c" }, # Successful JobRequest
  {
    "error": "Container not supported",
    "params": { "container": "non-existent-container" }
  },                                                # Failed JobRequest
  {},                                               # Successful DelegatedSubscriptionRequest
  {
    "error": "Container not supported",
    "params": { "container": "non-existent-container" }
  }                                                 # Failed DelegatedSubscriptionRequest
]

3. GET `/api/jobs`

Retrieves specific JobRequest 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.

Note: Results for DelegatedSubscriptionRequests are delivered on-chain (opens in a new tab), and cannot be fetched through this endpoint.

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": "openai-inference",
      "error": "Invalid input"
    },
    "intermediate": [],
    "status": "failed"
  }
]

[
  {
    "id": "3b0dc01e-1555-4ce4-8012-644f5e4c0dc7",
    "result": {
      "container": "openai-inference",
      "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"
]

4. PUT `/api/status`

Warning: DO NOT USE THIS ENDPOINT IF YOU DON'T KNOW WHAT YOU'RE DOING. This endpoint is meant to be used by containers that do NOT comply with Infernet, but still want to use it to record job IDs and statuses. This could be useful in the case of legacy images, where achieving Infernet compatibility (opens in a new tab) is impractical.

Registers job ID and status with the node.

Method: PUT
URL: /api/status

Body:

  {
    "id": string,
    "status": "success" | "failed" | "running"
    "containers": string[]
  }

id: ID of the job
status: Status of the job
containers: IDs of container(s) to associate with the job

Response:
- Success:
  - Code: 200 OK
- Failure:
  - Code: 400 Bad Request
  - Content: { "error": string }
    - error: Error message
    - params: Additional error parameters (if applicable).

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
}

DelegatedSubscriptionRequest

Similar to JobRequest, but creates a Subscription (opens in a new tab) and results are delivered on-chain (opens in a new tab), i.e. cannot be fetched via GET /api/jobs.

subscription (object) - The subscription parameters, see details (opens in a new tab).
- owner (string) - The on-chain address that owns a subscription.
- container_id (string) - Comma-separated string of the container ID(s) to run. Execution follows the pattern described under JobRequest.
- inputs (string, optional) - Encoded input data for the job.
- active_at (number) - The time after which to receive the first response.
- frequency (number) - The number of times to process a subscription.
- period (number) - The frequency at which to process a subscription.
- redundancy (number) - How many unique nodes to request responses from.
- max_gas_price (number) - The gas price limit of a response transaction.
- max_gas_limit (number) - The gas limit of a response transaction.
signature (object) - The signed EIP-712 Coordinator (opens in a new tab) function inputs, see details (opens in a new tab).
- nonce (number) - Subscribing contract nonce (included in signature)
- expiry (number) - Delegated subscription signature expiry (included in signature)
- v (number) - ECDSA recovery id
- r (number) - ECDSA signature output (r)
- s (number) - ECDSA signature output (s)
data (object) - The input data to be passed into the container.

{
    "subscription": Subscription,
    "signature": Signature,
    "data": object
}

JobResult

id (string) - Job UUID.
status (string) - "running", "success", or "failed".
result (object) - ContainerResult
intermediate (object[], optional) - Array of ContainerResults.

{
    "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.

Deployment Overview

REST API Reference

Endpoints

1. GET /info

2a. POST /api/jobs

2b. POST /api/jobs/batch

3. GET /api/jobs

4. PUT /api/status

Data Types

JobRequest

DelegatedSubscriptionRequest

JobResult

Container

ContainerOutput

ContainerError

ContainerResult

1. GET `/info`

2a. POST `/api/jobs`

2b. POST `/api/jobs/batch`

3. GET `/api/jobs`

4. PUT `/api/status`