Endpoint management API

Endpoints hold the target configuration and credential tiers for a connected database or service. API requests need an organization bearer token and the operation's control permissions. Backend data access uses separate data-plane permissions and credential profiles.

Use the running OpenAPI for full request/response fields and optional features. Database credentials describes target/credential isolation and encryption.

Create endpoint

POST /api/v1/endpoints
Authorization: Bearer <organization-token>
Content-Type: application/json
Idempotency-Key: <unique-intent-key-for-protected-HA-control>

The resource name field is endpoint. For PostgreSQL, use a target and explicit credential tiers:

{
  "endpoint": "mydb",
  "kind": "Postgres",
  "config": {
    "target": {"host": "postgres.internal.example", "port": 5432, "database": "app"},
    "read_credentials": {"username": "app_reader", "password": "<reader-secret>"},
    "write_credentials": {"username": "app_writer", "password": "<writer-secret>"}
  }
}

The PostgreSQL URL shorthand is config.url; do not nest it in write_conn. Embedded URL credentials become the default read/write credentials. Prefer separate least-privilege roles for production.

For an isolated Redis server with no TLS or authentication:

{
  "endpoint": "cache",
  "kind": "Redis",
  "config": {
    "target": {"host": "redis.internal.example", "port": 6379},
    "read_credentials": {},
    "write_credentials": {}
  }
}

For a secured deployment use Redis TLS and credentials. Do not mix Redis's target form with legacy connection fields. Other endpoint kinds have their own schemas; see Endpoint guides.

A synchronous creation response contains top-level id and uuid:

{"id":"cache","uuid":"11111111-1111-4111-8111-111111111111"}

Protected HA control can return 202 with operation_uuid and operation_url. Persist the idempotency key, follow the durable operation, and verify local endpoint activation before data requests. Acceptance and successful backend connectivity are separate checks.

List endpoints

curl --fail --silent --show-error \
  -H "Authorization: Bearer $EDEN_TOKEN" \
  "$EDEN_ORIGIN/api/v1/endpoints"

Parse the actual list schema in the deployed build. Listing visibility is permission-scoped; a missing item is not proof that no such endpoint exists in another organization or permission context.

Get endpoint

GET /api/v1/endpoints/{endpoint}
Authorization: Bearer <organization-token>

Use the endpoint ID or supported UUID form. Treat returned configuration and operational metadata as sensitive. Do not assume read responses include all private credentials or can be replayed verbatim as creation input.

Update endpoint

PATCH /api/v1/endpoints/{endpoint}
Authorization: Bearer <organization-token>
Content-Type: application/json

Use the patch schema from the live specification. Credential, target and TLS changes can replace connection generations and drain existing owners. Test new credentials and health before retiring old credentials. Protected HA updates require their documented idempotency/revision handling.

Delete endpoint

DELETE /api/v1/endpoints/{endpoint}
Authorization: Bearer <organization-token>

Check attached interlays, migrations, workflows and application traffic first. Follow lifecycle restrictions rather than deleting dependent control rows by hand. Removing an Eden endpoint resource is separate from deleting backend data.

Execute data operations

POST typed bodies such as {"request":{"type":"Get","key":"eden:example"}} to /api/v1/endpoints/{endpoint}/read or the matching write route. See Query execution, RBAC, release compatibility and reliable client behavior.