Getting Started

Getting Started#

Tudo que você precisa antes de chamar qualquer um dos seis produtos.

1. Base URL + formato#

Superfície URL
API https://data-api.catcher.one
Console (dashboard) https://data.catcher.one

Tudo é JSON (Content-Type: application/json), versão v1. As rotas dos produtos são /v1/clouddb/* (Database), /v1/cloudvec/* (Vector), /v1/cloudcache/* (Cache), /v1/cloudstore/* (Storage), /v1/cloudwiki/* (Wiki) e /v1/mcp (MCP).

2. Autenticação (API key)#

Para acesso programático / server-to-server, use uma API key no header:

text 
X-API-Key: ctc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

(Há também JWT Authorization: Bearer <token> para sessões de usuário no Console; para integrações use a API key. O MCP usa um token próprio — veja MCP.)

Mintar uma API key#

Keys são criadas por um owner (endpoint owner-only, exige email verificado) — pelo Console em API Keys, ou por API:

bash 
curl -sX POST https://data-api.catcher.one/v1/tokens \
  -H "Authorization: Bearer <owner-jwt>" \
  -H 'Content-Type: application/json' \
  -d '{ "label": "meu-servico", "role": "owner" }'
json 
{ "token_id": 12, "token": "ctc_…", "role": "owner", "last4": "ab12", "created_at": "…" }

⚠️ O valor token aparece uma única vez — guarde no seu secret manager. Opcional: allowed_source_ips (CSV de IPv4/IPv6/CIDR) prende a key a IPs. Revogue com DELETE /v1/tokens/{id}.

A partir daí, todo request leva -H "X-API-Key: ctc_…".

3. Papéis#

owner > admin > agent. Os produtos (Database, Vector, Cache, Storage, Wiki e a gestão do MCP) exigem owner ou admin. Um token agent recebe 403 FORBIDDEN nessas rotas.

4. Projetos vêm primeiro#

Database, Storage, Wiki e as coleções do Vector vivem dentro de um projeto. Um projeto = um projeto GCP + billing + estratégia de tenancy.

bash 
curl -sX POST https://data-api.catcher.one/v1/clouddb/projects \
  -H "X-API-Key: ctc_…" -H 'Content-Type: application/json' \
  -d '{ "name": "Produção", "hosting_mode": "catcher", "strategy": "row_level" }'
# → { "id": "<project-uuid>", ... }   guarde o id, ele é o {pid} das rotas
  • hosting_mode: catcher (infra + billing da Catcher, custo repassado com margem fixa) ou byo (seu próprio GCP/billing).
  • strategy: row_level (um schema compartilhado, coluna de tenant) ou schema_per_company (um schema por end-customer). Detalhes na página do Database.

O mesmo {pid} é usado pelo Storage (/v1/cloudstore/projects/{pid}/buckets), pelas coleções do Vector (/v1/cloudvec/projects/{pid}/collections) e pelos espaços da Wiki (/v1/cloudwiki/projects/{pid}/spaces).

Conta → Projeto → Tenant#

Há três níveis: sua Conta (de onde sai a API key), os Projetos dentro dela, e — se você atende vários clientes finais — os Tenants (o cliente do seu cliente). Um mesmo tenant_id isola um cliente final nos produtos, cada um com o mecanismo nativo da sua tecnologia. Veja Tenants antes de modelar multi-tenancy.

5. Envelope de erro#

Toda resposta de erro tem o mesmo formato:

json 
{ "error_code": "INSTANCE_NOT_READY", "message": "instance is not connected …",
  "trace_id": "2a62142c-…", "error": "…" }
  • error_code — código estável SCREAMING_SNAKE_CASE. Faça o match nisso (não na message). Cada módulo lista os seus na sua página.
  • trace_id — também vai no header X-Trace-ID. Cole no suporte para localizarmos a linha exata de log do backend.
  • Validações de campo podem trazer field_errors: [{field, message}].

Códigos genéricos por status: BAD_REQUEST (400), UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), UNPROCESSABLE_ENTITY (422), RATE_LIMITED (429), SERVICE_UNAVAILABLE (503).

6. Convenções#

  • Idempotência: criações que mutam aceitam Idempotency-Key: <uuid>; um retry com a mesma chave devolve o estado atual em vez de duplicar.
  • Paginação: onde existe, é ?page=&limit= (máx. 100) — a maioria das listas dos produtos é escopada (por projeto/coleção/espaço) e não pagina.
  • Feature flags: se um módulo não está habilitado no ambiente, suas rotas retornam 404 (não 403). Um 404 "fantasma" numa rota correta = módulo desligado; fale com o suporte.
  • Escopo por conta: a API key carrega a sua conta; você só enxerga os recursos dela. Isolamento entre contas é validado por suite de pentest contínua (cross-tenant, auth, RBAC, injeção).
  • Assíncrono: provisionar uma instância de Database, ativar um Cache dedicado e ingerir um arquivo (Vector/Wiki) são operações assíncronas — a resposta é imediata (pending/provisioning/processing) e você faz poll do status.

Próximo passo#

Vá para o produto que você vai usar: Database · Vector · Cache · Storage · Wiki · MCP — e leia Tenants se o seu app atende múltiplos clientes finais.