Querying the Eden Service API reference

Use the specification served by the same Eden Service build you will call. It contains operation IDs, methods, paths, request/response schemas, parameters, and security requirements. The human-readable API reference and complete public API index also cover runtime-mounted families and provide examples. The generated Service REST operation catalog lists handler annotations across all source features, with links and a searchable method/path table; it complements the build-specific live contract.

Fetch the complete document

Set EDEN_ORIGIN to the origin of your service, without /api/v1. The default local HTTP port is 8000. Use HTTPS through your deployment's ingress remotely.

export EDEN_ORIGIN=http://127.0.0.1:8000
curl --fail --silent --show-error \
  "$EDEN_ORIGIN/api-docs/openapi.json" --output eden-openapi.json
jq '{openapi, info, servers, path_count: (.paths | length)}' eden-openapi.json

These discovery routes are mounted outside the organization-authenticated /api/v1 scope. They do not require an Eden JWT. An ingress may add its own authentication, and deployment-wide admission can still apply. Downloading a schema grants no permission to call an operation. Swagger's Authorize action supplies credentials to API calls; Try it out executes real operations.

The document is generated and cached at process startup. It is not a query of live tenant resources. Refresh the downloaded document after upgrading Eden.

Discover a smaller API area

curl --fail --silent --show-error "$EDEN_ORIGIN/api-docs/index.json" \
  --output eden-openapi-index.json
jq -r '.documents[] | [.name, .url, .path_count, .description] | @tsv' \
  eden-openapi-index.json

# Fetch a partition actually advertised by this service.
curl --fail --silent --show-error \
  "$EDEN_ORIGIN/api-docs/openapi/migrations.json" \
  --output eden-migrations-openapi.json

Partition names are fixed, but empty partitions are omitted from the index:

Partitions are selected by path, not tags. Each includes reachable components; it is suitable for focused browsing and importing into an OpenAPI client.

Query operations and schemas with jq

List every operation without accidentally treating path-level parameters as HTTP methods:

jq -r '
  .paths | to_entries[] | .key as $path | .value | to_entries[]
  | select(.key | test("^(get|put|post|delete|options|head|patch|trace)$"))
  | [(.key | ascii_upcase), $path, (.value.operationId // ""),
     (.value.summary // "")] | @tsv
' eden-openapi.json

Find Redis migration operations, inspect a particular operation, list schemas, and inspect authentication schemes:

jq -r '.paths | keys[] | select(test("migration|interlay|redis"; "i"))' eden-openapi.json
jq '.paths["/api/v1/endpoints"].post |
    {operationId, parameters, requestBody, responses, security}' eden-openapi.json
jq -r '.components.schemas | keys[]' eden-openapi.json
jq '{default_security: .security, schemes: .components.securitySchemes}' eden-openapi.json

# Resolve a schema selected from the list above.
jq --arg name "$SCHEMA_NAME" '.components.schemas[$name]' eden-openapi.json

Operations can override top-level security. Follow $ref values under #/components/… for the exact body and response types; do not assume all resources share one response envelope. Use the path exactly as emitted: service operations normally include /api/v1 already. Do not prepend it a second time.

Import the JSON file into an OpenAPI-aware HTTP client or use it as input to your chosen client generator. Keep the downloaded schema with the service version used to generate the client, review authentication configuration, and exercise the generated client against that deployment before upgrading it.

Authenticate an API request

User login uses HTTP Basic authentication and X-Org-Id, and returns {"token":"…"}. It does not accept the illustrative JSON email/password body or return accessToken/refreshToken fields.

# curl prompts for the password; do not put it in shell history.
umask 077
curl --fail --silent --show-error --user "$EDEN_USERNAME" \
  --header "X-Org-Id: $EDEN_ORG_ID" \
  --request POST "$EDEN_ORIGIN/api/v1/auth/login" \
  --output /tmp/eden-login.json

Protect the response file as a credential. Use the returned .token as the bearer for later requests. For unattended clients, read credentials from a protected secret file using the HTTP client's credential facility.

EDEN_TOKEN=$(jq -er '.token' /tmp/eden-login.json)
curl --fail --silent --show-error \
  --header "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/endpoints"

The request runs in the authenticated organization's scope and requires the operation's permissions. Agent API-key login and external identity have separate contracts; see authentication and the security model rather than substituting a Prometheus scrape token for a user JWT.

Build profiles and completeness

The openapi Cargo feature enables discovery and Swagger UI. It is included in server-runtime/server-runtime-headless, but is not part of the default feature list. For a development build:

cargo run --locked -p eden-service --features openapi

Configure the normal service/datastore prerequisites before running. Build features cannot be added to an already-built container with an environment variable. The external-offline-redis-trial profile intentionally omits OpenAPI; use its packaged docs/API_REFERENCE.md and migration guide.

“Complete document” means all operations registered by that build's OpenAPI assembler. It is not a union of every product, protocol, and feature:

• External-datastore and embedded-datastore builds use different assemblers.

The embedded assembler currently has narrower coverage; absence from its document alone does not prove that a runtime route is unavailable.

• Optional workflow, endpoint-comparison, stream, VPN, DevOps, and bootstrap

operations follow their feature gates. Consult the live index and route reference for the image in use.

• Native Redis RESP, PostgreSQL/MySQL wire protocols, gRPC, and event streams

are not fully described by the REST OpenAPI document.

• Eden Orchestrator and Licensing are separate servers with their own routes

and contracts. The Eden Service document does not describe their full APIs.

Use the workflow operations present in the running build's specification and matching workflow guide. Follow the documented preparation and approval gates; API discovery does not grant migration readiness or cutover approval.

Troubleshooting and sources

Authoritative sources: mounts, discovery and partitioning, external assembler, embedded assembler, feature profiles, login handler.