--- title: API HTTP description: Consulte cabeçalhos, rotas, status e erros da API HTTP. sidebar: order: 1 --- A API HTTP do Siglata expõe serviços essenciais de espaço de trabalho, fluxos de autenticação e pipelines de transferência de dados. A API oferece tratamento de erros tipado, limites multi-inquilino rigorosos e suporte completo a internacionalização. A URL base padrão de produção é: ```text https://www.siglata.com ``` ## Cabeçalhos Padrão [#standard-headers] Todas as requisições para a API do Siglata utilizam cabeçalhos HTTP padronizados: | Cabeçalho | Descrição | Exemplo | | :-- | :-- | :-- | | `Authorization` | Token Bearer para requisições autenticadas da API e transferências MCP. | `Bearer sig_acc_9f8a7...` | | `x-siglata-locale` | Idioma de preferência para e-mails transacionais, modelos de convite e mensagens de erro localizadas. | `en-US` ou `pt-BR` | | `Content-Type` | Formato da carga útil. O padrão é `application/json` para endpoints de controle e `application/octet-stream` para blocos binários de arquivos. | `application/json` | | `Origin` | Validado nos endpoints do MCP e CORS para evitar abusos de origens cruzadas. | `https://exemplo.com` | ## API do Serviço Principal [#core-api] ### Verificação de Saúde e Sessão Inspecione a disponibilidade da API, a localização ativa e a identidade da sessão atual. ```http GET /api HTTP/1.1 Host: www.siglata.com Authorization: Bearer x-siglata-locale: pt-BR ``` #### Resposta (`200 OK`) ```json { "service": "siglata", "status": "ok", "locale": "pt-BR", "user": { "id": "usr_9f8a7b6c5d", "email": "alex@exemplo.com", "name": "Alex Smith", "image": null } } ``` Quando chamado sem uma sessão ativa ou token, `user` retorna `null`. ## Endpoints de Autenticação (`/auth/*`) [#auth-endpoints] Os endpoints de autenticação administram credenciais sem senha, sessões e organizações multi-inquilino. ### Solicitar Link Mágico Envia um link de acesso de uso único para o endereço de e-mail do usuário no idioma solicitado. ```http POST /auth/sign-in/magic-link HTTP/1.1 Host: www.siglata.com Content-Type: application/json x-siglata-locale: pt-BR { "email": "alex@exemplo.com" } ``` #### Resposta (`200 OK`) ```json { "status": true } ``` ### Verificar Link Mágico Valida o token do link mágico de uso único e define um cookie de sessão seguro e HTTP-only. ```http GET /auth/magic-link/verify?token=tok_3b4c5d6e7f HTTP/1.1 Host: www.siglata.com ``` ### Obter Sessão Ativa Recupera a sessão atualmente autenticada e o registro do usuário. ```http GET /auth/get-session HTTP/1.1 Host: www.siglata.com ``` ### Encerrar Sessão (Sign Out) Invalida a sessão ativa e remove os cookies de autenticação. ```http POST /auth/sign-out HTTP/1.1 Host: www.siglata.com ``` ### Gerenciamento de Organizações Administre os limites e funções de espaços de trabalho multi-inquilino: #### Criar Organização `POST /auth/organization/create` - **Corpo**: `{ "name": "Acme Corp", "slug": "acme-corp" }` - **Resposta**: Registro da organização criada com seu ID. #### Listar Organizações do Usuário `GET /auth/organization/list` - **Resposta**: Lista de organizações às quais o usuário pertence, incluindo suas funções. #### Obter Detalhes da Organização `GET /auth/organization/get?organizationId=org_1a2b3c4d5e` - **Resposta**: Perfil detalhado da organização, membros e metadados. #### Convidar Membro da Equipe `POST /auth/organization/invite-member` - **Cabeçalhos**: `x-siglata-locale: pt-BR` (ou `en-US`) - **Corpo**: `{ "email": "dev@exemplo.com", "role": "member", "organizationId": "org_1a2b3c4d5e" }` - **Resposta**: Registro do convite criado. #### Listar Convites Pendentes `GET /auth/organization/list-invitations?organizationId=org_1a2b3c4d5e` - **Resposta**: Lista de convites pendentes. #### Cancelar Convite `POST /auth/organization/cancel-invitation` - **Corpo**: `{ "invitationId": "inv_9a8b7c6d5e" }` #### Atualizar Função de Membro `POST /auth/organization/update-member-role` - **Corpo**: `{ "memberId": "usr_3c4d5e6f7g", "role": "admin", "organizationId": "org_1a2b3c4d5e" }` #### Remover Membro `POST /auth/organization/remove-member` - **Corpo**: `{ "memberIdOrEmail": "usr_3c4d5e6f7g", "organizationId": "org_1a2b3c4d5e" }` ### Endpoints de Descoberta OAuth 2.0 O Siglata publica documentos de descoberta padrão para clientes OAuth 2.0 e MCP: - `GET /.well-known/oauth-authorization-server` - `GET /.well-known/openid-configuration` - `GET /.well-known/oauth-protected-resource/v1/mcp` ## Endpoints do Model Context Protocol e Transferências (`/v1/mcp/*`) [#mcp-endpoints] Os endpoints `/v1/mcp/*` processam mensagens do protocolo JSON-RPC e transferências de arquivos binários de alto rendimento. O `tools/list` expõe apenas duas ferramentas, `execute` e `search`, e as operações de gerenciamento rodam dentro de scripts `execute`. ### Streamable HTTP para JSON-RPC ```http POST /v1/mcp HTTP/1.1 Host: www.siglata.com Authorization: Bearer Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "execute", "arguments": { "script": "return await files_list({ state: 'active', limit: 25 });" } } } ``` ### Enviar Parte Binária (Upload de Bloco) Transfere uma parte individual de 8 MiB para uma reserva de upload ativa criada via `upload_begin`. ```http PUT /v1/mcp/uploads/{uploadId}/parts/{partNumber} HTTP/1.1 Host: www.siglata.com Authorization: Bearer Content-Type: application/octet-stream ``` - `partNumber`: Inteiro indexado a partir de 1 (de 1 a 10.000). - Resposta: `200 OK` mediante validação e gravação bem-sucedida do bloco. ### Download Binário Autenticado Transmite os bytes do arquivo armazenado diretamente para o chamador autorizado. ```http GET /v1/mcp/files/{fileId}/download HTTP/1.1 Host: www.siglata.com Authorization: Bearer ``` - **Resposta**: `200 OK` com `Content-Type` correspondente ao tipo de mídia original, `Content-Length` e `Content-Disposition: attachment`. - Valida a associação ativa na organização antes de iniciar a transmissão dos bytes. ## Códigos de Status HTTP [#status-codes] | Status | Código | Significado | | :-- | :-- | :-- | | `200` | OK | Requisição bem-sucedida; dados retornados. | | `201` | Created | Recurso criado com sucesso (por exemplo, organização, convite). | | `204` | No Content | Ação concluída com sucesso sem corpo de resposta. | | `400` | Bad Request | Carga malformada, esquema inválido ou divergência no tamanho do bloco. | | `401` | Unauthorized | Token de autenticação ausente ou inválido, ou sessão expirada. | | `403` | Forbidden | Escopo OAuth insuficiente, associação obrigatória ou origem não permitida. | | `404` | Not Found | Arquivo, upload, organização ou convite de destino não encontrado. | | `409` | Conflict | Cota de armazenamento excedida ou conflito de estado concorrente. | | `410` | Gone | A reserva de upload expirou ou a janela de 30 dias na lixeira terminou. | | `500` | Internal Error | Exceção na execução do lado do servidor. | ## Taxonomia de Erros [#error-taxonomy] O Siglata retorna erros tipados e estruturados com códigos legíveis por máquina: ```json { "code": "quota_exceeded", "message": "Storage quota limit reached for this organization" } ``` ### Códigos de Erro Comuns | Código de Erro | Status HTTP | Descrição | | :-- | :-- | :-- | | `invalid_input` | 400 | Um ou mais parâmetros falharam nas regras de validação. | | `part_mismatch` | 400 | O tamanho da parte não corresponde aos 8 MiB esperados. | | `upload_incomplete` | 400 | Tentativa de concluir o upload com partes ausentes. | | `SESSION_EXPIRED` | 401 | A sessão autorizadora expirou; reautenticação obrigatória. | | `INSUFFICIENT_SCOPE` | 403 | A concessão OAuth não possui o escopo necessário para esta operação, ou o teto `maxScopes` MCP da organização o exclui. | | `MCP_ACCESS_REVOKED` | 403 | O acesso MCP da organização está `revoked`. Linhas ausentes passam a `testing` automaticamente. | | `ORGANIZATION_MEMBERSHIP_REQUIRED` | 403 | O usuário não é membro ativo da organização solicitada. | | `ORGANIZATION_ADMIN_REQUIRED` | 403 | A operação exige privilégios de `owner` ou `admin`. | | `ORIGIN_NOT_ALLOWED` | 403 | Origem da requisição rejeitada pela política de segurança CORS. | | `not_found` | 404 | Registro de arquivo, upload ou organização não encontrado. | | `INVITATION_NOT_FOUND` | 404 | O ID de convite informado não existe. | | `quota_exceeded` | 409 | O upload não pode prosseguir porque ultrapassaria o limite de 10 GiB. | | `conflict` | 409 | Modificação concorrente ou conflito de estado. | | `upload_expired` | 410 | A reserva de upload expirou antes da conclusão. | | `restore_expired` | 410 | O arquivo ultrapassou o período de recuperação de 30 dias da lixeira. | | `storage_failure` | 500 | O backend de armazenamento encontrou um erro inesperado. | | `database_failure` | 500 | Falha em consulta ou transação no banco de dados. |