Skip to Content
We are live but in Staging 🎉
API ReferenceAPI Conventions

API Conventions

Use this page as the baseline for all K3 API calls.

Transport and Endpoints

  • gRPC API: k3-api on K3_GRPC_ADDR (default :50051)
  • HTTP API: k3-api on K3_S3_PROXY_ADDR (default :8080)
  • Documentation examples in this repository use https://k3.dev.dodil.io as the HTTP base URL.

Most user-facing integrations use HTTP routes documented in this folder.

Auth and Tenant Headers

Send these headers on authenticated HTTP requests:

  • Authorization: Bearer <token>
  • x-organization-id: <org_id>
  • x-organization-name: <org_name> (optional, mostly dev/test flows)

Route Style

  • Bucket-scoped resources use /:bucket/...
  • Admin/global resources use /admin/...
  • IDs are usually opaque strings (source_id, pipeline_id, collection_id, rule_id, job_id)

Pagination Pattern

List RPCs commonly use cursor pagination:

  • Request: pagination.page_size, pagination.page_token
  • Response: pagination.next_page_token, pagination.total_count

Notes:

  • page_size=0 means server default (commonly 50).
  • total_count=-1 means unavailable or expensive to compute.

Optional Update Semantics

K3 uses wrappers for update requests to avoid ambiguity:

  • StringList and StringMap wrappers:
    • field absent: do not change
    • field present but empty: clear existing values
    • field present and non-empty: replace

For plain optional scalar fields:

  • unset: do not change
  • set (including empty string/zero): update to provided value

Compatibility and Runtime Notes

  1. Canonical vector search route is POST /:bucket/vector/search.
  2. Compatibility vector search route also exists: POST /:bucket/search/vector.
  3. Object routes in live router are key-in-path style:
    • GET /:bucket/objects/:key/info
    • DELETE /:bucket/objects/:key
    • GET /:bucket/objects/:key/url
  4. If proto annotation and runtime router differ, treat runtime router as source of truth.

Reusable cURL Template

export K3_TOKEN="<bearer_token>"
export K3_ORG="<org_id>"
 
curl -sS "https://k3.dev.dodil.io/<path>" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json"

Next: StorageService

K3 API ReferenceStorageService API