Infernet
Node
REST API

REST API Reference

The REST API enables twofold functionality:

  1. It allows initiating, checking the status of, and fetching results for off-chain Web2 compute requests
  2. It allows initiating on-chain Web3 requests via a Delegated Subscription

Endpoints

GET /health

Retrieves server health.

  • Method: GET
  • URL: /health
  • Response:

GET /info

Retrieves information about the node, including chain information, which containers are running, and the number of jobs pending.

  • Method: GET
  • URL: /info
  • Response:
    • Success:

POST /api/jobs

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

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)[ ]
  • Response:
    • Success:
      • Code: 200 OK

      • Content: (JobResponse | DelegatedSubscriptionResponse | ErrorResponse) []

        • Array of JobResponse, DelegatedSubscriptionResponse, or ErrorResponse 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
        ]

POST /api/jobs/stream

Creates a new off-chain streaming job. Only direct compute requests (JobRequest) are allowed, since the results are streamed, i.e. returned synchronously. The full results can also be fetched asynchronously through /api/jobs using the Job UUID returned by this endpoint (see Response below).

NOTE: The Content-Type of the response may vary based on success / failure, as well as selected container. It's the responsibility of the caller to inspect the status code and handle the response appropriately. The first yielded chunk of a success response will always contain the full Job UUID, but caller's handling of the remaining response must be container-aware.

  • Method: POST
  • URL: /api/jobs/stream
  • Body: JobRequest
  • Response:
    • Success:

      • Code: 200 OK
      • Content: A stream of bytes, initially yielding the job ID, followed by streaming job results.

      Initial yield example:

      1548865f-e806-41df-a756-f427c1d2e395

      Subsequent yield examples:

      a subset
      of
      machine
      learning,

      ...

      ...

      ...

    • Failure:


GET /api/jobs

Retrieves JobResult objects if 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).
  • Response:

    • Success:
      • Code: 200 OK
      • Content: JobResult[]
        • If intermediate=true, includes intermediate results.

PUT /api/status

Warning: MAKE SURE YOU 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.

Restricted to localhost only.

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:

Data Types

HealthInfo

Health of the Infernet node.

  • status (string) - Health status of the server
{
  "status": "healthy" | "unhealthy"
}

NodeInfo

Information about the Infernet node.

  • version (string) - Node version
  • containers (Container[]) - Array of Container objects
  • pending (object) - Job counts
    • offchain (number) - Offchain jobs pending
    • onchain (number) - Onchain jobs pending
  • chain (object) - Chain information
    • enabled (boolean) - Whether chain is enabled
    • address (string) - Node's wallet address
{
  "version": string,
  "containers": Container[],
  "pending": {
    "offchain": number,
    "onchain": number
  },
  "chain": {
    "enabled": boolean,
    "address": string
  }
}

JobRequest

Specifies a direct compute request, which consists of running one or more containers. If n > 1 containers are specified, the output of container i is the 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].
  • requires_proof (boolean, optional) - Whether the job requires proof of execution. Default is false.
{
    "containers": string[],
    "data": object,
    "requires_proof": boolean
}

JobResponse

The response for direct compute requests, containing the newly created Job UUID.

  • id (string) - A Job UUID
{
    "id": string
}

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[]
}

ErrorResponse

Error response with relevant message and optional parameters.

  • error (string) - Error message
  • params (object, optional) - Additional error parameters (if applicable).
{
  "error": string
  [, "params": 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
}

DelegatedSubscriptionResponse

The response for delegated subscription requests is empty.

Since results for delegated subscriptions can only be fetched on-chain, there is no job UUID for off-chain retrieval.

{}

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.