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:
  • Success:
    • Code: 200 OK
    • Content: HealthInfo

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:
    • Code: 200 OK
    • Content: NodeInfo

GET /resources

Retrieves resources of the running containers, which include hardware specifications and supported model information.

If a model ID is provided, checks containers for model support. Otherwise, fetches full service resources.

• Method: GET
• URL: /resources
• Query Parameters:
  • model_id (string, optional): Model IDs to return support information for.
• Response:
  • Code: 200 OK
  • Content:
    • Key: (string) - The container ID.
    • Value: One of
      • (ModelSupport) - A ModelSupport object, if model_id specified
      • (ServiceResources) - A ServiceResources object, otherwise

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 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)[ ]
  • Array of JobRequests and / or DelegatedSubscriptionRequests
• 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 GET /api/jobs using the Job UUID returned by this endpoint (see Response below).

• 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:

    • Code: 4xx / 5xx
    • Content: ErrorResponse

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, 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:

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

PUT /api/status

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: ErrorResponse

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 and results are delivered on-chain, i.e. cannot be fetched via GET /api/jobs.

• subscription (object) - The subscription parameters, see details.

  • 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 function inputs, see details.

  • 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.

MLModel

Represents a machine learning model.

• owner (string) - The organization that owns the model.
• name (string) - The name of the model.
• repository (string) - The repository where the model is stored.
• storage (string) - The storage backend where the model is stored
• files (string[]) - List of files associated with the model.
• version (string) - The version of the model.
• ml_type (string) - The type of machine learning model.

{
  "owner": string,
  "name": string,
  "repository": string,
  "storage": string,
  "files": string[],
  "version": string,
  "ml_type": string
}

CPUInfo

The CPU information of the hardware capability.

• architecture (string) - CPU architecture.
• byte_order (string) - CPU byte order.
• cores (string[]) - CPU cores.
• model (string) - CPU model.
• num_cores (integer) - Number of CPU cores.
• vendor_id (string) - CPU vendor ID.

{
  "architecture": string,
  "byte_order": string,
  "cores": string[],
  "model": string,
  "num_cores": integer,
  "vendor_id": string
}

DiskInfo

Disk information of the hardware capability.

• available (integer) - Available disk space.
• filesystem (string) - Filesystem type.
• mount_point (string) - Disk mount point.
• size (integer) - Total disk size.
• used (integer) - Used disk space.

{
  "available": integer,
  "filesystem": string,
  "mount_point": string,
  "size": integer,
  "used": integer
}

OSInfo

OS information of the hardware capability.

• name (string) - OS name.
• version (string) - OS version.

{
  "name": string,
  "version": string
}

ServiceResources

• service_id (string) - The unique identifier for the inference service.
• compute_capability (object[]) - List of compute capabilities available for the service.
  • id (string) - Identifier for the compute capability.
  • type (string) - Type of inference service (e.g., CSS, ONNX).
  • task (string[]) - List of tasks supported by the compute capability.
  • models (MLModel[]) - List of MLModel objects supported by the compute capability.
  • cached_models (MLModel[]) - List of MLModel objects that are cached for faster access.
  • inference_engine (string, optional) - Inference engine used by the compute capability.
  • inference_engine_version (string, optional) - Version of the inference engine.
• hardware_capabilities (HardwareCapability[]) - List of hardware capabilities available for the service.
  • capability_id (string) - Unique identifier for the hardware capability.
  • cpu_info (CPUInfo) - CPUInfo object.
  • disk_info (DiskInfo) - DiskInfo object.
  • os_info (OSInfo) - OSInfo object.

ModelSupport

Model support information for a container.

• supported (boolean) - Whether the model ID is supported.
• error (string, optional) - A message explaining why the model ID is unsupported or erroneous.

{
  "supported": boolean,
  "error": string
}