curl --request POST \
  --url https://public-api.revilico.bio/v1/engines/revfunction/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Ubiquitin function",
  "parameters": {
    "proteins": [
      {
        "id": "P0CG48_ubiquitin",
        "sequence": "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
      }
    ],
    "share_sequences_outside_revilico": true
  },
  "inputs": {}
}
'

{
  "id": "<string>",
  "engine": "<string>",
  "name": "<string>",
  "access": "owner",
  "owner": {
    "name": "<string>",
    "email": "<string>"
  },
  "status": "queued",
  "statusReason": "<string>",
  "progress": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "budget": 123,
  "creditsUsed": 123,
  "error": {
    "message": "<string>"
  },
  "links": {},
  "children": {
    "total": 123,
    "queued": 123,
    "running": 123,
    "succeeded": 123,
    "failed": 123,
    "cancelled": 123
  },
  "warnings": [
    "<string>"
  ]
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request is malformed."
  }
}

{
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "The API key is missing or not valid."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your organization doesn't have enough credits."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The key may not do this."
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found, or not visible to you."
  }
}

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "The parameters or input files don't fit the engine."
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong on our side."
  }
}

{
  "error": {
    "code": "ENGINE_SUBMIT_FAILED",
    "message": "The engine service rejected or failed the request."
  }
}

Engine runs

Start a RevFunction run

Reads protein sequences and writes, for each one, a plain-language account of what the protein probably does: its likely activity, the processes it takes part in and where in the cell it works. Alongside it lists the known building blocks (domains) found in the sequence and predicted Gene Ontology terms (standard function labels). Each sequence is sent to a public service outside Revilico to find its domains, so the request must confirm that with share_sequences_outside_revilico. Runs take minutes to hours, mostly waiting on that service; progress jumps from 0 to 100, and a run cannot be cancelled once submitted.

Starts a run and returns it with status queued; poll GET /v1/runs/ until it finishes. Runs spend credits.

Limits: maxProteins: 100, maxResidues: 2000, maxIdLength: 64.

Scope: runs:write.

POST

engines

revfunction

runs

curl --request POST \
  --url https://public-api.revilico.bio/v1/engines/revfunction/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Ubiquitin function",
  "parameters": {
    "proteins": [
      {
        "id": "P0CG48_ubiquitin",
        "sequence": "MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG"
      }
    ],
    "share_sequences_outside_revilico": true
  },
  "inputs": {}
}
'

{
  "id": "<string>",
  "engine": "<string>",
  "name": "<string>",
  "access": "owner",
  "owner": {
    "name": "<string>",
    "email": "<string>"
  },
  "status": "queued",
  "statusReason": "<string>",
  "progress": 123,
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "endedAt": "2023-11-07T05:31:56Z",
  "budget": 123,
  "creditsUsed": 123,
  "error": {
    "message": "<string>"
  },
  "links": {},
  "children": {
    "total": 123,
    "queued": 123,
    "running": 123,
    "succeeded": 123,
    "failed": 123,
    "cancelled": 123
  },
  "warnings": [
    "<string>"
  ]
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request is malformed."
  }
}

{
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "The API key is missing or not valid."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your organization doesn't have enough credits."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The key may not do this."
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found, or not visible to you."
  }
}

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "The parameters or input files don't fit the engine."
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong on our side."
  }
}

{
  "error": {
    "code": "ENGINE_SUBMIT_FAILED",
    "message": "The engine service rejected or failed the request."
  }
}

Authorizations

Authorization

string

header

required

An API key from the web app (Settings → Developer), sent as Authorization: Bearer rvl_live_….

Body

application/json

parameters

object

required

Show child attributes

name

string

A name for the run, shown in the web app.

Maximum string length: 200

inputs

object

budget

number

Most credits the run may spend; it is stopped beyond that.

projectId

string

Add the run to this project (proj_…); needs editor or owner on it.

Response

string

required

Run id, run_….

engine

string

required

Engine slug, e.g. revredox.

name

string | null

required

access

enum<string>

required

Why you can see the run: you started it, it was shared with you, or it is in a project you belong to. Only the owner can cancel it or read its inputs.

Available options:

owner,

shared,

project

owner

object

required

Who started the run.

Show child attributes

status

enum<string>

required

queued until the engine picks the run up; succeeded, failed and cancelled are final.

Available options:

queued,

running,

succeeded,

failed,

cancelled

statusReason

string | null

required

Why a cancelled run stopped: user, insufficient_credits or budget_exceeded. Null otherwise.

progress

number

required

Progress the engine reports; 0 until it reports any.

createdAt

string<date-time>

required

startedAt

string<date-time> | null

required

endedAt

string<date-time> | null

required

budget

number | null

required

Most credits the run may spend, if one was set.

creditsUsed

number

required

Credits charged to the run so far.

error

object | null

required

Set when status is failed.

Show child attributes

links

object

required

Related endpoints: self, inputs (owner only), results, outputs, files.

Show child attributes

children

object

For engines that run each input as its own job: how many children are in each status. GET /v1/runs/{runId}/children lists them.

Show child attributes

warnings

string[]

Set when the run was created but a follow-up step, such as adding it to a project, failed.

Get started

Guides

MCP server

API reference

Endpoints

Start a RevFunction run

Authorizations

Body

Response