Visão geral da API - Qoder CN Series: Central de Documentação do Alibaba Cloud

A API do Qoder Cloud Agents oferece recursos completos para gerenciar AI Agents em cloud, incluindo criação de Agent, configuração de ambiente, gerenciamento de sessões e streaming de eventos. Todos os endpoints seguem o design RESTful e utilizam JSON como formato de requisição e resposta.

A API está atualmente em Beta. Alguns recursos podem sofrer ajustes em versões futuras.

URL do gateway

Ambiente	URL
Produção	`https://api.qoder.com.cn/api/v1/cloud`

Versionamento

A versão atual da API é v1. Todos os endpoints incluem a versão no caminho da URL (/v1/); portanto, não é necessário um header de versão separado.

APIs disponíveis

Recurso	Descrição	Caminho base
Agents	Crie, leia, atualize, exclua e arquive instâncias de Agent	`/agents`
Environments	Gerencie configurações do ambiente de execução	`/environments`
Sessions	Crie sessões de Agent e gerencie seu ciclo de vida	`/sessions`
Events	Leia e envie streams de eventos de sessão	`/events`
Files	Envie arquivos e gerencie associações	`/files`
Vaults	Armazene credenciais sensíveis com segurança	`/vaults`
Skills	Registre e gerencie habilidades do Agent	`/skills`
Memory Stores	Armazenamento persistente de memória	`/memory_stores`
Deployments	Automação de deploy agendado	`/deployments`
Forward Templates	Definição, versionamento, arquivamento e clonagem de modelos de Forward Agent	`/api/v1/forward/templates`
Forward Identities	Criação, ativação, desativação e exclusão de identidades Forward, além de consultas de Agent	`/api/v1/forward/identities`
Forward Identity Configs	Configuração de modelo por identidade e consultas à configuração efetiva	`/api/v1/forward/identities/{identity_id}/templates`
Forward Channels	Gerenciamento de canais Forward e sessões de código QR	`/api/v1/forward/channels`, `/api/v1/forward/qr_sessions`
Forward Sessions	Ciclo de vida, eventos e streams SSE de sessões Forward	`/api/v1/forward/sessions`
Forward Resources	Registro e listagem de recursos externos Forward	`/api/v1/forward/resources`
Forward Schedules	Gerenciamento de tarefas agendadas Forward e histórico de execuções	`/api/v1/forward/schedules`, `/api/v1/forward/schedule_runs`

Limites de tamanho de requisição

Tamanho máximo do corpo da requisição por chamada: 4 MB.
O servidor trunca corpos que excedem o limite. Isso causa falha na análise do JSON e retorna um erro 400 invalid_request_error (mensagem: "Request body must be valid JSON.").

Headers de requisição obrigatórios

Toda requisição à API deve incluir o header de autorização. Recomendamos também incluir o Content-Type:

Authorization: Bearer $QODER_PAT
Content-Type: application/json  # Recommended but not mandatory; the server can auto-detect

Status Beta

A API apresenta estabilidade geral, mas as assinaturas de requisição podem sofrer pequenos ajustes nas próximas iterações.
Novos recursos são lançados sob novos identificadores beta.
Em produção, fixe a versão da API e implemente tratamento de compatibilidade.
Todos os recursos atuais funcionam sem um header Beta adicional.

Verificação rápida de conectividade

# List Agents under the current account to verify authentication and connectivity
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

Uma resposta bem-sucedida tem o seguinte formato:

{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Limitação de taxa

Atualmente, não há limites de taxa no nível da aplicação. O gateway aplica controles globais de tráfego em rajada e proteção contra DDoS, que podem retornar status 429 ou 503 sob carga elevada. Para respostas 5xx e 429, tente novamente com backoff exponencial (1 s, 2 s, 4 s — até três tentativas).

Próximos passos

Autenticação — Obtenha e utilize um PAT.
Erros — Códigos de erro e solução de problemas.
Paginação — Paginação de endpoints de lista.