HTTP API

All endpoints are served from a common base URL and versioned under /v1.

https://api.euriklis.com/v1/…

Request bodies are encoded as application/json, except where an endpoint accepts file uploads and requires multipart/form-data. Successful responses are always application/json, with the exception of the ECU stream, which is text/event-stream. Numeric quantities are transmitted as JSON numbers; large matrices are transmitted as nested arrays of numbers.

Endpoints that consume ECU or that access user-scoped resources are authenticated by an API key supplied in the x-api-key request header. Keys are issued from the API keys panel of the dashboard and may be revoked or rotated at any time.

curl https://api.euriklis.com/v1/data/uploads \
  -H "x-api-key: $EURIKLIS_API_KEY"

A missing key returns 401 with {"error":"Missing x-api-key header"}; an unknown key returns 401 with {"error":"Invalid API key"}. Endpoints that do not consume ECU (GET /v1/health, GET /v1/info, GET /v1/operations) are unauthenticated.

All JSON responses share a common envelope structure. Successful responses carry a Boolean success: true and a data object whose shape is endpoint-specific. Error responses carry success: false, a human-readable error string, and — where produced by static validation — a details array of diagnostic strings.

{
  "success": false,
  "error": "Invalid computation graph",
  "details": [
    "nodes[0].operations[1].arguments.x: expected matrix, received undefined"
  ]
}

The principal endpoint of the platform. Accepts a JSON-encoded computational graph, validates it, executes it, and returns the entry-node result together with the total ECU consumption. The request grammar is fully specified in DAG schema.

{
  "success": true,
  "data": {
    "result": { "AAt": [[…], […], […]] },
    "ecuUsed": 3
  }
}

The resultobject maps each placeholder listed in the entry node's return array (with the leading $ and any state. prefix stripped) to its computed value. When the request body is multipart/form-data, the JSON graph is supplied under the graph field and one or more files as additional parts — the mechanism is described on the DAG schema page.

Programmatic enumeration of the operation registry. The response contains, for every operation, its description and its JSON Schema — suitable for driving IDE completions, contract tests, or generated client stubs.

{
  "success": true,
  "data": {
    "math.matrix.svd": {
      "description": "",
      "inputSchema": { "type": "object", "properties": { … }, "required": [ … ] }
    },
    "math.matrix.random": { … },
    "finance.efficientFrontier": { … }
    …
  }
}

Human-readable narrative endpoints. Suited to shell exploration and to quick self-service documentation from within an agent session; the canonical machine-readable equivalent is the operation discovery endpoint (§5).

{
  "success": true,
  "data": { "message": "Euriklis API is working correctly." },
  "ecu": 0
}

Returns a narrative summary of the API — request grammar, submission instructions, and pointers to the reference material.

Returns package-scoped narrative documentation. Currently defined for math; further packages become available as they are added to the registry.

Files may be uploaded independently of a compute request and later referenced by identifier. This is the recommended pattern for reusable data (large tables, calibration matrices) that participate in multiple graphs. Uploads are scoped to the owning API key and persist until explicitly deleted or until the server's storage-eviction policy retires them.

curl -X POST https://api.euriklis.com/v1/data/upload \
  -H "x-api-key: $EURIKLIS_API_KEY" \
  -F "file=@dataset.xlsx"

{
  "success": true,
  "data": {
    "id": "3f5a0b28-9e5b-4a44-bd57-9c8e9c6e2c11",
    "name": "dataset.xlsx",
    "size": 41283
  }
}

The returned id is subsequently used inside a compute request under the top-level files map. See the DAG schema page for the injection mechanism.

Lists the caller's uploads.

{
  "success": true,
  "data": [
    {
      "id": "3f5a0b28-9e5b-4a44-bd57-9c8e9c6e2c11",
      "name": "dataset.xlsx",
      "size": 41283,
      "uploadedAt": "2026-07-21T09:14:22.008Z"
    }
  ]
}

Deletes an upload by identifier. Body: {"id": "<upload-id>"}. Returns {"success": true} on success.

A convenience endpoint for locating equity ticker symbols by free-text query. Intended as a companion to the finance operations, particularly when constructing a portfolio-analysis graph interactively.

{
  "success": true,
  "data": [
    { "symbol": "AAPL", "shortname": "Apple Inc.", "exchange": "NMS" },
    { "symbol": "AAPL.MX", "shortname": "Apple Inc.", "exchange": "MEX" }
    …
  ]
}

A server-sent-events endpoint that emits an event whenever the caller's ECU consumption changes. Suitable for live dashboards and for programmatic quota monitoring. The initial event upon connection reports the current state.

data: {"ecuUsed": 3421, "ecuBalance": 96579}

data: {"ecuUsed": 3424, "ecuBalance": 96576}

HTTP status codes distinguish the failure class. Validation failures are reported with structured details and do not incur ECU consumption.