API

The Skynet HTTP API lets scripts and tools do what the web app does: start runs, watch them, and read the results. This page shows how to sign requests, where the full reference is, and one complete example.

Base URL

Send every request to:

https://api.skynetml.com

Authentication

The API uses API tokens.

1. Open Settings in Skynet, then open the API tab.
2. Click Generate token.
3. Copy the token at once. Skynet shows the full token only one time.

Send the token in the Authorization header of every request:

Authorization: Bearer skyd_...

• Tokens start with skyd_.
• Each user has at most one valid token. A new token stops the old token.
• Click Revoke token to stop a token.

Interactive reference

The full reference is at api.skynetml.com/scalar. It lists each public endpoint, its fields and its responses. You can send test requests from that page.

The reference reads the OpenAPI document at https://api.skynetml.com/openapi.public.json. Use that file to generate a client in your language.

Main endpoints

Start a run

POST /optimize takes the same setup as the submit wizard. This example improves a prompt that sorts support messages into labels.

curl https://api.skynetml.com/optimize \
  -H "Authorization: Bearer $SKYNET_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-labels-001" \
  -d @run.json

{
  "name": "Support labels",
  "task": {
    "objective": "Sort each support message into billing, bug or other.",
    "artifact": {
      "kind": "prompt",
      "starting_version": "Label this support message as billing, bug or other."
    }
  },
  "data": {
    "mode": "pairs",
    "cases": [
      { "input": { "message": "I was charged twice." }, "expected": { "label": "billing" } },
      { "input": { "message": "The export button does nothing." }, "expected": { "label": "bug" } },
      {
        "input": { "message": "Do you have a Hebrew interface?" },
        "expected": { "label": "other" }
      }
    ]
  },
  "optimizer": { "choice": "auto", "budget": { "max_scorer_runs": 200 } },
  "models": {
    "task_model": { "name": "<model from GET /models>" },
    "reflection_model": { "name": "<model from GET /models>" }
  },
  "workspace": {
    "run_code": "from skynet import llm\n\ndef run(artifact, input):\n    return llm(artifact, input=input[\"message\"])\n",
    "metric_code": "def score(input, output, expected=None):\n    ok = str(output).strip().lower() == expected[\"label\"]\n    return (1.0 if ok else 0.0), {\"feedback\": \"Correct.\" if ok else \"Wrong label.\"}\n"
  },
  "max_cost_cents": 500
}

Important fields:

• task.artifact.kind is prompt, code, text or dspy_program.
• data.mode is pairs (inputs with expected outputs) or single (exactly one case).
• optimizer.choice is auto or one optimizer name from GET /optimizers.
• max_cost_cents is the spending limit for this run, in US cents.
• is_private is false by default. Set it to true to keep the run private.

Read Metrics and scorers for the rules of run_code and metric_code.

Responses

Watch a run

Poll the run until its status is final:

curl https://api.skynetml.com/optimizations/$RUN_ID \
  -H "Authorization: Bearer $SKYNET_TOKEN"

The status field is one of:

Poll every 10 to 30 seconds. A run can take from minutes to hours.

The API reference lists every field of the run response.

Use the result

When the status is success, get the best version:

curl https://api.skynetml.com/optimizations/$RUN_ID/artifact \
  -H "Authorization: Bearer $SKYNET_TOKEN"

To run the best version on a new input, send POST /serve/{optimization_id}. Read Results for what each score means.

Limits

The API uses the same quotas, rate limits and billing as the web app. Read Limits and Billing.