Passo a passo da API com respostas capturadas

Ambiente e respostas capturadas

As respostas nesta página foram capturadas das rotas reais do sidecar em 15 outubro 2026 usando apps/sidecar/test/helpers.ts. Esse equipamento cria os manipuladores de aplicativos com um banco de dados SQLite na memória migrado, um diretório de arquivos descartável, o host direto de IA e nenhuma chamada de provedor. As solicitações passam pelo roteador HTTP em processo; esta execução não utiliza o iniciador Tauri, soquetes de rede, TLS ou um telefone emparelhado.

Os corpos de resposta abaixo não foram editados. Identificadores e carimbos de data e hora pertencem, portanto, a essa execução descartável. Sua instância retorna seus próprios valores. Use o identificador do projeto retornado pela sua solicitação de criação em vez de reutilizar o identificador capturado.

CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-api-walkthrough \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.ts

Este token de exemplo é apenas para um processo de desenvolvimento isolado. Escolha seu próprio valor, mantenha o terminal aberto e leia a porta do evento JSON ready. Em um segundo terminal, defina as variáveis de conexão abaixo após substituir READY_PORT. O sidecar escolhe uma nova porta em outro lançamento.

export CADCAMFUN_URL="http://127.0.0.1:READY_PORT"
export CADCAMFUN_TOKEN="local-development-token"

O banco de dados de desenvolvimento em disco difere do banco de dados na memória da captura. Se você reutilizar esse diretório de dados, os projetos e preferências criados anteriormente permanecerão. Use um diretório descartável separado para uma nova execução. O desktop empacotado usa seu diretório de dados de aplicativo nativo.

Verifique a saúde

/api/health é a sonda pública. Confirma que esta rota responde; ele não testa credenciais, um fornecedor de modelo ou recursos de fabricação.

curl --silent --show-error "$CADCAMFUN_URL/api/health"

{
  "status": "ok",
  "timestamp": "2026-10-15T02:43:50.682Z"
}

O nativo /health e /version as operações requerem o token de portador do aplicativo. Leia seus contratos exatos no referência do sistema.

Entenda a autorização

Uma solicitação de projeto sem token ao portador é rejeitada antes que os dados do projeto sejam retornados.

curl --silent --show-error --include "$CADCAMFUN_URL/api/projects"

{
  "_tag": "Unauthorized",
  "message": "Unauthorized"
}

O erro contém seu nome de erro marcado e uma mensagem legível. Não analise a mensagem como um código de erro estável. O status HTTP, o esquema do endpoint e sua tag declarada descrevem juntos a falha.

Usar Authorization: Bearer … para chamadas de inscrição admitidas. Um opcional x-session-token seleciona uma sessão de conta após a admissão do portador. Os tokens de ponte AI podem chamar apenas as duas rotas de ponte de ação; eles não podem substituir um token de aplicativo neste passo a passo. Os tokens complementares são aceitos pelo gateway emparelhado com sua própria política de rota.

Leia e crie um projeto

curl --silent --show-error "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

[]

A resposta é uma matriz simples, sem um data ou success invólucro. Uma solicitação de criação estruturalmente válida, mas incompleta, é rejeitada pela validação comercial:

curl --silent --show-error --request POST "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

{
  "_tag": "BadRequest",
  "message": "Project name is required"
}

O esquema de transporte faz name opcional, mas o manipulador requer um valor não vazio. Para criar o projeto:

curl --silent --show-error --request POST "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"API walkthrough","description":"Disposable documentation example"}'

{
  "id": "ccaff34c-49f3-4a23-a6b6-427745f9641a",
  "name": "API walkthrough",
  "description": "Disposable documentation example",
  "createdAt": "2026-10-15T02:43:50.741Z",
  "updatedAt": "2026-10-15T02:43:50.741Z",
  "ownerId": "894c5064-576e-4e43-b7f0-79c6120e8345",
  "organizationId": null,
  "isPublic": false
}

O resultado da criação é a nova linha do projeto. Omitido isPublic torna-se falso nesta execução; nenhuma organização está selecionada. O proprietário é o perfil local atuante. Atribuir uma organização requer adesão; atualizar um projeto existente também verifica seu proprietário ou função na organização.

Leia os dados relacionados

Copie o identificador retornado pela sua solicitação de criação para PROJECT_IDe leia a rota detalhada:

export PROJECT_ID="your-returned-project-id"
curl --silent --show-error "$CADCAMFUN_URL/api/projects/$PROJECT_ID" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

{
  "id": "ccaff34c-49f3-4a23-a6b6-427745f9641a",
  "name": "API walkthrough",
  "description": "Disposable documentation example",
  "createdAt": "2026-10-15T02:43:50.741Z",
  "updatedAt": "2026-10-15T02:43:50.741Z",
  "ownerId": "894c5064-576e-4e43-b7f0-79c6120e8345",
  "organizationId": null,
  "isPublic": false,
  "owner": {
    "id": "894c5064-576e-4e43-b7f0-79c6120e8345",
    "name": "Local user",
    "email": "local@cadcamfun.local"
  },
  "organization": null,
  "_count": {
    "drawings": 0,
    "components": 0
  }
}

Os detalhes incluem o proprietário, a organização anulável e as contagens de desenhos/componentes. A criação e a recuperação têm esquemas de resposta relacionados, mas diferentes. Um projeto ausente ou inacessível retorna 404 com Project not found or access denied; os chamadores não devem inferir a existência de um projeto privado a partir desse resultado.

API de projetos também atualiza e exclui documentos. A atualização requer um nome não vazio; a exclusão requer o proprietário ou um administrador da organização. Não implemente a atualização como um patch JSON arbitrário sem seguir seu contrato de carga útil.

Listas paginadas, como configurações de máquina, aceitam page (padrão 1) e limit (padrão 20, máximo 100) e retornar um pagination objeto com total e totalPages. Solicite a próxima página em vez de aumentar limit além da tampa; valores maiores são fixados em 100.

Persistir uma preferência

A API de valor-chave demonstra um segundo formato de resposta e comportamento de recursos ausentes. Uma chave que não foi salva retorna 404:

curl --silent --show-error "$CADCAMFUN_URL/api/kv/docs.walkthrough.units" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

{
  "_tag": "NotFound",
  "message": "Key not found"
}

Salve um valor compatível com JSON com PUT. Este é um exemplo de preferência; não altera globalmente as unidades do kernel da geometria.

curl --silent --show-error --request PUT "$CADCAMFUN_URL/api/kv/docs.walkthrough.units" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"value":"mm"}'

{
  "key": "docs.walkthrough.units",
  "value": "mm",
  "updatedAt": "2026-10-15T02:43:50.755Z"
}

A leitura da mesma chave retorna a entrada armazenada, incluindo seu carimbo de data/hora de atualização. A resposta não agrupa o valor em um registro de projeto ou envelope de sucesso.

{
  "key": "docs.walkthrough.units",
  "value": "mm",
  "updatedAt": "2026-10-15T02:43:50.755Z"
}

Usar GET /api/kv?prefix=docs.walkthrough. para listar entradas correspondentes ou DELETE a chave codificada para removê-la. A loja rejeita chaves em branco, chaves muito longas e valores fora do seu domínio compatível com JSON. Não é um cofre de credenciais.

Lidar com falhas e novas tentativas

Em clientes de produção, verifique response.ok e decodifique o corpo de sucesso ou erro apropriado. Evite confiar em um envelope uniforme: somente este passo a passo inclui uma matriz, registros simples e falhas marcadas.

Próximas etapas de integração

Use o referência completa para selecionar um recurso. O extremidades de usinagem distinguir computação de salvar um percurso; o pontos finais do histórico distinguir alterações na cópia de trabalho de commits e sincronização remota. O Recurso de IA abrange identificadores de sessão e controles de streaming.

Leia o sidecar em execução /api/openapi.json ao integrar uma compilação diferente. O instantâneo da documentação para download descreve o contrato verificado; ele não pode estabelecer qual binário outra máquina está executando.

Todas as respostas capturadas num piscar de olhos

As respostas nesta página foram capturadas de um sidecar real com um novo banco de dados. Identificadores e carimbos de data/hora serão diferentes em sua máquina; formas e status não.

Todo o passeio como um roteiro

#!/usr/bin/env bash
set -euo pipefail
: "${CADCAMFUN_URL:?set to the sidecar URL}" "${CADCAMFUN_TOKEN:?set to the launch token}"
auth=(--header "Authorization: Bearer $CADCAMFUN_TOKEN")
json=(--header "Content-Type: application/json")

curl -sS "$CADCAMFUN_URL/api/health"; echo
curl -sS -o /dev/null -w "no token -> %{http_code}\n" "$CADCAMFUN_URL/api/projects"
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/projects"; echo
curl -sS "${auth[@]}" "${json[@]}" -d '{}' "$CADCAMFUN_URL/api/projects"; echo   # 400

id=$(curl -sS "${auth[@]}" "${json[@]}" \
  -d '{"name":"API walkthrough","description":"Disposable documentation example"}' \
  "$CADCAMFUN_URL/api/projects" | sed -E 's/.*"id":"([^"]+)".*/\1/')
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/projects/$id"; echo

key=docs.walkthrough.units
curl -sS -w " %{http_code}\n" "${auth[@]}" "$CADCAMFUN_URL/api/kv/$key"   # 404 first time
curl -sS -X PUT "${auth[@]}" "${json[@]}" -d '{"value":{"units":"mm"}}' "$CADCAMFUN_URL/api/kv/$key"; echo
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/kv/$key"; echo

O roteiro usa sed extrair o id para que não tenha dependências; com jq instalado, prefira jq -r .id. Execute-o em um diretório de dados descartável: ele cria um projeto real.

Limpe após o passeio

curl -sS -X DELETE --header "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects/$id"
curl -sS -X DELETE --header "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/kv/docs.walkthrough.units"

A exclusão do projeto se espalha para seus desenhos, componentes, percursos da ferramenta de ferramenta, histórico e execuções de fluxo de trabalho. A entrada do valor-chave é independente e deve ser removida separadamente.

Em 3D