API HTTP

Consulte cabeçalhos, rotas, status e erros da API HTTP.

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 é:

https://www.siglata.com

Cabeçalhos Padrão

Todas as requisições para a API do Siglata utilizam cabeçalhos HTTP padronizados:

API do Serviço Principal

Verificação de Saúde e Sessão

Inspecione a disponibilidade da API, a localização ativa e a identidade da sessão atual.

GET /api HTTP/1.1
Host: www.siglata.com
Authorization: Bearer <token-opcional>
x-siglata-locale: pt-BR

Resposta (200 OK)

{
  "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/*)

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.

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)

{
  "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.

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.

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.

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/*)

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

POST /v1/mcp HTTP/1.1
Host: www.siglata.com
Authorization: Bearer <token-de-acesso-oauth>
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.

PUT /v1/mcp/uploads/{uploadId}/parts/{partNumber} HTTP/1.1
Host: www.siglata.com
Authorization: Bearer <token-de-acesso-oauth>
Content-Type: application/octet-stream

<bytes binários brutos: exatamente 8.388.608 bytes, ou os bytes restantes para a parte final>

• 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.

GET /v1/mcp/files/{fileId}/download HTTP/1.1
Host: www.siglata.com
Authorization: Bearer <token-de-acesso-oauth>

• 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

Taxonomia de Erros

O Siglata retorna erros tipados e estruturados com códigos legíveis por máquina:

{
  "code": "quota_exceeded",
  "message": "Storage quota limit reached for this organization"
}

Códigos de Erro Comuns