Skip to main content
Alchemy’s API is ConnectRPC, generated from the protobuf definitions in protos/functions/v1/ and protos/metrics/v1/. The server mounts three services on one listener: The built-in web UI and the @galaxy-io/alchemy-ui module call this same API. Every RPC has a Connect HTTP POST route at /<package.Service>/<Method>:
The server binary listens on ADDR (default :8780). The same listener also serves the plain HTTP invoke endpoint, /healthz, /scaling and the web UI, described in HTTP endpoints.

Protocols

The server accepts HTTP/1.1 and unencrypted HTTP/2 (h2c) on the same plaintext port, so all three ConnectRPC wire protocols work against it directly. A proxy in front of the server must speak HTTP/2 to it for plain gRPC to pass through. The Connect protocol is JSON over POST, so any HTTP client works for unary RPCs. Field names are lowerCamelCase in JSON, and bytes fields such as input are base64:
Here input is {"id":"abc"} in base64. The streaming RPCs, GetInvocationLogs and TailInvocations, use Connect’s streaming envelope and need a Connect, gRPC or gRPC-Web client. For invoking from scripts, the HTTP invoke endpoint takes the raw input as the body instead. Unary calls may set a deadline with Connect-Timeout-Ms (or grpc-timeout). Invoke waits for its result until that deadline, capped at INVOKE_MAX_DEADLINE (default 1 hour), or INVOKE_DEADLINE (default 5 minutes) when the call sets none.

Authentication

With AUTH_PROVIDER unset, the API is unauthenticated and every request runs in the default tenant. Keep such deployments private or protect them at the network layer. With a provider configured, every RPC requires a caller except the AuthService session procedures: GetAuthConfig, Login, GetToken, Logout, Register and AcceptInvite. How the caller is read depends on the provider: The same check guards the HTTP invoke endpoint. See Authentication for configuring a provider.

Tenancy

The tenant comes from the caller. A token’s organization (or the gateway’s tenant header) resolves to an Alchemy tenant, created on first sight. With authentication disabled, every request uses the built-in default tenant. Request bodies never select a tenant. Functions, versions, invocations, instances, secrets and metrics are scoped to it. ListHosts and GetHost report the cluster’s hosts, which every tenant of the deployment shares.

Pagination

ListFunctions, ListFunctionVersions and ListInvocations take an optional PaginationRequest. The response’s PaginationResponse carries total, the count before the page was cut, and previous_cursor and next_cursor when a page exists in that direction. Omitting pagination returns every row, up to 10,000. A cursor the server cannot decode is invalid_argument.

Errors

Failures are standard Connect error codes. These are the codes the server returns. Some specifics worth knowing:
  • An input that violates its contract is invalid_argument with one functions.v1.ContractViolation error detail per failure.
  • failed_precondition covers invoking a function with no ready version or a version that is not ready, spec.secrets or secret_values on a server with no secret provider, spec.source on a server with no artifacts bucket, and an idempotency_key on Invoke when the server has no logs bucket.
  • A function that ran and failed is not an RPC error. Invoke succeeds and its response carries a FunctionError.

API areas

Functions

Functions, their immutable versions, and the runtimes a source can build on.

Invocations

Invoking, reading invocation records, streaming logs and live transitions.

Hosts

The live hosts and the microVMs they are running.

Secrets

How a function version names and creates tenant secrets.

Metrics

Timeseries, aggregates and the in-flight queue.

HTTP endpoints

Plain HTTP invoke, health and the autoscaling feed.