HTTP API

The hosted API runs comparisons at https://cyteonto.nygen.io. Requests and responses are JSON. The service also serves interactive documentation at /docs and its OpenAPI schema at /openapi.json.

A job runs in the background: submit it, poll its status until it is completed or failed, then download the results. The hosted API quickstart shows these steps with curl and Python.

POST /compare¶

Submit the author labels and the labels of one or more algorithms. Only authorLabels and algorithms are required; the other fields select the models and the options of the comparison, as the arguments of CyteOnto.compare() do in Python.

The default models match the precomputed ontology files. With another LLM or embedding model, the job first describes or embeds the 2,902 Cell Ontology terms for that model pair, which takes much longer. The service calls the LLM through the provider’s OpenAI-compatible API. If descriptions fail, the service retries them with its fallback LLM, Kimi K2.6 on Fireworks, and the status reports it. It also falls back to Qwen3-Embedding-8B on OpenRouter when embeddings fail; the first job that does so also embeds the 2,902 ontology descriptions with that model, which takes longer. The schema also accepts ollama as embeddingProvider, but the service has no Ollama server: each such job first tries to reach it for every ontology term and then switches to the fallback model, so do not use it with the hosted API. See Choose the embedding provider.

The response holds the new job’s run ID:

{"runId": "run-<uuid>", "state": "queued"}

Request options¶

Options go in the same body as the labels. This request scores compound labels with hungarian_mean, leaves weak matches unmatched and widens the kernel of the metric:

curl -sS -X POST "https://cyteonto.nygen.io/compare" \
  -H 'Content-Type: application/json' \
  -d '{
    "authorLabels": ["AT2 cell-plasma cell doublet", "regulatory T cell"],
    "algorithms": {"method_a": ["plasma cell", "Treg"]},
    "compoundScoring": "hungarian_mean",
    "minMatchSimilarity": 0.5,
    "metricParams": {"width": 0.5}
  }'

To send your own API keys, build the body with jq, which quotes the values of shell variables correctly. Inside the single quotes of -d '...', the shell would send $NEBIUS_API_KEY as literal text:

jq -n --arg key "$NEBIUS_API_KEY" '{
  authorLabels: ["alveolar macrophage", "regulatory T cell"],
  algorithms: {method_a: ["lung macrophage", "Treg"]},
  llmApiKey: $key,
  embeddingApiKey: $key
}' | curl -sS -X POST "https://cyteonto.nygen.io/compare" \
  -H 'Content-Type: application/json' -d @-

GET /status/{runId}¶

Returns the state of a job.

A job normally moves from queued to running and ends as completed or failed. A job that stops unexpectedly can keep its last state, so stop polling after a time limit.

GET /result/{runId}¶

Returns the results of a completed job. The format query parameter selects the format:

• format=json, the default, returns a JSON array with one object per row.

• format=csv returns a CSV file named <runId>.csv.

Both have the columns described in Read the results.

GET /health¶

Returns {"ok": true} when the service is up.

Errors¶

Errors are JSON objects with a detail field.

Other problems show up while the job runs. A job fails, with the reason in error, for example when an algorithm is named author, when no API key is available for a provider, or when the labels cannot be embedded. The service does not check your API keys when you submit a job. If the provider rejects an LLM key, the fallback LLM may describe the labels instead and the job completes, so check modelPairUsage.

Privacy¶

The service has no accounts: anyone who has a run ID can read the job’s status and results. Run IDs are random, but share them only with people who may see your labels. The service sends your labels to the LLM and embedding providers of the job, and may send them to its fallback providers, Fireworks and OpenRouter, even when you select others. With usePubmedTool, the model’s search terms go to NCBI. The service keeps the status, the results and the label splits, descriptions and embeddings of each job.