Skip to main content

Endpoints API

Endpoints are webhook source receivers — the public-facing URLs where providers send events.

Status: WIRED_SANDBOX. This page describes the current contract surface and known non-claims. It is not a production-live availability claim.

Terminology​

Customer termInternal API/model termAPI path
Endpointingester/ingesters

Audience​

Customer / developer configuring webhook sources.

Base path​

/api/bff/v1/tenants/{tenant_id}/clusters/{cluster_id}/ingesters     (dashboard/BFF — app-facing, INTERNAL_ONLY)
/v1/tenants/{tenant_id}/ingesters                                   (backend API — WIRED_SANDBOX)

Endpoint table​

MethodPathDescriptionRead/WriteStatusAuth/scopesIdempotencyOpenAPI
GET/tenants/{tid}/ingestersList endpointsReadWIRED_SANDBOXread:ingestersNot requiredPartial (zen-back)
POST/tenants/{tid}/ingestersCreate an endpointWriteWIRED_SANDBOXwrite:ingestersRecommendedPartial (zen-back)
GET/tenants/{tid}/ingesters/{iid}Get endpoint detailsReadWIRED_SANDBOXread:ingestersNot requiredPartial (zen-back)
PUT/tenants/{tid}/ingesters/{iid}Update an endpointWriteWIRED_SANDBOXwrite:ingestersRecommendedPartial (zen-back)
DELETE/tenants/{tid}/ingesters/{iid}Delete an endpointWriteWIRED_SANDBOXwrite:ingestersRecommendedPartial (zen-back)

Read/write status​

OperationReadWriteStatus
List endpointsYes—WIRED_SANDBOX
Create endpoint—YesWIRED_SANDBOX
Get endpoint detailsYes—WIRED_SANDBOX
Update endpoint—YesWIRED_SANDBOX
Delete endpoint—YesWIRED_SANDBOX

Write operations require tenant authorization, appropriate scopes, and audit logging. See Write Safety Model for details.

List example​

curl -sS -H "Authorization: Bearer <api_key>" \
  "https://api.zen-mesh.io/v1/tenants/<tenant_id>/ingesters"

Create example​

curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique_key>" \
  -d '{"name": "stripe-endpoint", "type": "stripe"}' \
  "https://api.zen-mesh.io/v1/tenants/<tenant_id>/ingesters"

Error examples​

400 Validation error​

{
  "type": "https://api.zen-mesh.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "type: must be a valid provider type",
  "instance": "req_abc123"
}

403 Insufficient scope​

{
  "type": "https://api.zen-mesh.io/errors/insufficient-scope",
  "title": "Insufficient Scope",
  "status": 403,
  "detail": "API key does not have write:ingesters scope.",
  "required_scope": "write:ingesters"
}

Pagination​

List endpoints supports pagination with limit and cursor parameters. See Pagination and Filtering.

Auth​

Bearer JWT or API key in Authorization header. Tenant-scoped via path parameter. See Authentication for scope model.

OpenAPI coverage​

Partially covered in zen-back.v1.yaml (ingesters CRUD under /clusters). See OpenAPI Spec Index.

UI mapping​

Connect → Endpoints

Non-claims​

  • WIRED_SANDBOX: implemented in local/sandbox runtime. Not production-live.
  • Provider-specific endpoints (Stripe, GitHub, etc.) have provider-specific validation paths.
  • Public endpoint URLs on shared receive IPs (Free tier) vs dedicated IPs (Business+).