Function specification#

What POST /v1/functions ({metadata, spec}) and PUT /v1/functions/{name} ({spec}, the draft whole) take. A version keeps the spec it was published from.

{
  "metadata": {"name": "weather"},
  "spec": {
    "runtime": "python",
    "code": "def handler(city: str):\n    return {\"city\": city}\n",
    "handler": "handler",
    "dependencies": ["requests==2.32.3"],
    "description": "Get the weather for a city.",
    "env": {"UNITS": "metric"},
    "credentials": [{"credential": "owm", "env": {"key": "OWM_API_KEY"}}],
    "timeout_seconds": 20,
    "memory_mb": 512,
    "cpu_cores": 1,
    "isolation": "sandbox",
    "scaling": {"concurrency": 8, "min_instances": 0, "max_instances": 4, "queue": 64, "idle_seconds": 300},
    "http": {"enabled": true}
  }
}

Field	Type	Default	Meaning
`runtime`	`python` \| `node`	`python`	Python 3.12, or Node.js 22.
`code`	string	required	The code: one file, at most 256 KiB. Node code with `export`/`import` lines is an ES module, else CommonJS.
`handler`	string	`handler`	The function in the code that is called.
`dependencies`	list of strings	`[]`	Packages installed when an instance starts: pip requirements (`requests==2.32.3`) or npm packages (`[email protected]`). At most 100, each one line of at most 200 characters; options (`-…`) are refused.
`description`	string	—	What it does (at most 1000 characters).
`env`	map	`{}`	Environment variables, at most 64, each value at most 4096 bytes. Names starting `ASTRAEUS_` are refused. Not for secrets.
`credentials`	list	`[]`	At most 16 Credentials of the workspace: `{credential, env}`, `env` mapping their keys to variables; without `env`, their files at `/credentials/<name>/<key>`. Resolved on the machine.
`timeout_seconds`	integer	`30`	1–900: the longest one call may take.
`memory_mb`	integer	`512`	128–65536: memory of each instance.
`cpu_cores`	integer	`1`	1–64: its share of CPU; it may use idle cores beyond.
`gpu`	`{count, min_memory_gb, vendor}`	none	GPUs of one machine for each instance: `count` 1, 2, 4 or 8; `vendor` `nvidia`, `amd` or any. Needs `isolation: container`.
`isolation`	`sandbox` \| `container`	`sandbox`	`sandbox`: under gVisor. `container`: a plain container, weaker — only when you choose it.
`scaling.concurrency`	integer	`8`	1–1000 calls one instance serves at once.
`scaling.min_instances`	integer	`0`	Instances kept warm for each version `latest` or an alias names (never for the draft). `0`: scaled to zero when idle. At most `max_instances`.
`scaling.max_instances`	integer	`4`	1–64.
`scaling.queue`	integer	`64`	0–10000 calls that wait when every instance is busy; beyond: `429 FUNCTION_BUSY`.
`scaling.idle_seconds`	integer	`300`	30–86400 s without a call before the instances above `min_instances` stop.
`http.enabled`	boolean	`false`	Answer at its URL on the gateways, with an API key that lists the function.

What the API answers#

GET /v1/functions/{name} adds:

Field	Meaning
`latest`	The newest version (`0`: none yet).
`aliases`	Aliases → versions, `latest` included.
`draft_changed`	Whether the draft differs from the newest version.
`instances[]`	Per target served (`draft`, `v<n>`, with the `aliases` naming it): instances wanted (`desired`), `ready`, in all (`current`), and why (`reason`).

A version (GET /v1/functions/{name}/versions/{v}) is {function, version, spec, digest, schema, note, published_by, published_at}; digest is the SHA-256 of its spec, schema is {description, parameters, warnings} — what a model is told it takes.

Names and aliases#

A function's name: lower-case letters, digits and -, starting with a letter, at most 30 characters.
An alias: the same rule; not latest (the newest version, always), draft, or v<n>. At most 32 aliases.
A function's instances are named fn-<function>-<target>-<i>-0 (fn-weather-v2-0-0), where <target> is draft or v<n>.