Emita pedidos de compra, aprove e pague faturas, e configure seu espaço de trabalho.

Referência da API

Provedores de IA

Provedores de IA conectados diretamente com uma chave somente leitura, e os faturadores de IA que você pode adicionar como fornecedores.

Mais sobre este recurso

Novo com os controles de gastos com IA. Além das linhas de IA das suas faturas de nuvem, a Pleaxy lê os relatórios de custo e uso dos provedores de IA que você paga diretamente. OpenAI e Anthropic usam uma chave de administrador somente leitura; a Mistral também, quando a organização tem a Admin API (um recurso Enterprise); a OpenRouter, uma chave de gerenciamento; a CoreWeave, um token de acesso à API com a função Billing Viewer; a Databricks, o segredo OAuth de uma entidade de serviço; para a Snowflake, a Pleaxy gera um par de chaves cuja chave pública você atribui a um usuário de serviço. Lambda, Nebius, Crusoe e os faturadores por assento (Cursor, GitHub, Microsoft) não têm uma API de faturamento que a Pleaxy consiga ler: adicione-os como fornecedores e as faturas deles serão verificadas contra o contrato. A chave é verificada com uma leitura antes de qualquer coisa ser salva, armazenada criptografada, nunca retornada (só os quatro últimos caracteres, keyHint) e nunca usada para alterar nada no provedor. As linhas de cada provedor conectado são lidas diariamente e aparecem em Gastos com IA como um faturador próprio, confrontadas com os pedidos de compra emitidos para o cadastro de fornecedor dele. Cada faturador de IA tem um cadastro de fornecedor que a Pleaxy cria previamente e que você pode adicionar sem conectar: as faturas e os pedidos dele passam a funcionar como os de qualquer fornecedor. Um provedor conectado conta para o limite de provedores do plano, como uma conta de nuvem. O conector de cada provedor é ativado por região; até lá, conectar responde 404 e adicionar o fornecedor continua funcionando.

Endpoints

GET…/ai-providers
POST…/ai-providers
POST…/ai-providers/{id}/sync
DELETE…/ai-providers/{id}
POST…/ai-providers/{provider}/supplier
GET…/ai-invoicers

Listar provedores de IA

Lista os provedores de IA conectados do espaço de trabalho.

GET/v1/workspaces/{regionId}/ai-providers

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Cada conexão direta com um provedor de IA no espaço de trabalho, conectada ou pendente: qual é o provedor, a conta que ela lê, os quatro últimos caracteres da chave, quando foi sincronizada pela última vez e como foi. A chave em si nunca é retornada. Exige acesso 'view' a fornecedores ou a faturas.

Campos da resposta

accountLabelstring
Como o provedor chama a organização ou conta que a chave lê.
keyHintstring
Os quatro últimos caracteres da chave, o único vestígio dela que a Pleaxy mostra. Ausente para a Snowflake, cujo par de chaves a Pleaxy gerou.
statusstring
connected, ou pending para um par de chaves da Snowflake cuja chave pública ainda não foi atribuída ao usuário de serviço: SyncAiProvider o verifica e conclui a conexão.
snowflakeobject
Só Snowflake: o identificador da conta, o usuário de serviço, o warehouse e a função opcional com que o par de chaves se autentica, e a chave pública (PEM) e sua impressão digital para atribuir com ALTER USER ... SET RSA_PUBLIC_KEY.
creditPriceobject
Só Snowflake: o preço por crédito do seu contrato, que converte créditos em dinheiro. Sem ele, as linhas de IA do provedor ficam em créditos, com currency credits, e nunca são somadas a dinheiro.
supplierConnectionIdstring
O cadastro de fornecedor ao qual o provedor está vinculado; Gastos com IA confronta suas linhas com os pedidos de compra emitidos para ele.
currencystring
A moeda de faturamento do provedor, como o relatório de custos dele a informa.
lastSyncStatusstring
Como foi a última leitura: ok, error (lastSyncError diz por quê; lastSyncErrorCode é access_revoked quando a chave não funciona mais) ou throttled (o provedor pediu à Pleaxy que esperasse; a próxima execução tenta de novo).

Erros

401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

GET /v1/workspaces/{regionId}/ai-providers

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

[
   {
      "id": "string",
      "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave",
      "accountLabel": "string",
      "keyHint": "string",
      "status": "connected" | "pending",
      "connectedAt": "string",
      "connectedBy": "string",
      "snowflake": { "account": "string", "user": "string", "warehouse": "string", "role": "string", "publicKeyPem": "string", "publicKeyFingerprint": "string" },
      "creditPrice": { "amount": number, "currency": "string", "kind": "on_demand" | "capacity" | "commit" },
      "supplierConnectionId": "string",
      "currency": "string",
      "lastSyncedAt": "string",
      "lastSyncStatus": "ok" | "error" | "throttled",
      "lastSyncError": "string",
      "lastSyncErrorCode": "string"
   }
]

Criar provedor de IA

Conecta um provedor de IA com uma chave somente leitura.

POST/v1/workspaces/{regionId}/ai-providers

Corpo

provider"openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave"Obrigatório
O provedor a conectar. O conector dele precisa estar ativado na região.
keystring
Todo provedor exceto Snowflake, obrigatório: uma chave somente leitura. A chave de administrador da OpenAI começa com sk-admin- (Organization settings › Admin keys); a da Anthropic, com sk-ant-admin (Claude Console, Settings › Admin keys); a da Mistral é uma chave da Admin API; a chave de gerenciamento da OpenRouter começa com sk-or-; a da CoreWeave é um token de acesso à API; a da Databricks é o segredo OAuth da entidade de serviço. Nunca registrada em log e nunca retornada.
snowflakeobject
Snowflake, obrigatório: { account, user, warehouse, role? }: o identificador da conta (orgname-account_name), o usuário de serviço, o warehouse em que a consulta de uso roda e uma função opcional.
databricksobject
Databricks, obrigatório: { host, clientId, warehouseId }: o host do workspace (um domínio da Databricks), o client id OAuth da entidade de serviço e o SQL warehouse em que rodam as leituras de faturamento; key é o segredo OAuth da entidade. A entidade precisa de SELECT em system.billing (e em system.serving para as contagens de tokens).
creditPriceobject
Snowflake e Databricks, opcional: { amount, currency, kind }, com kind on_demand, capacity ou commit: o preço por crédito (Snowflake) ou por DBCU (Databricks) do seu contrato. Sem ele, as linhas da Snowflake ficam em créditos e as da Databricks ficam no preço de lista da conta.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Conecta um provedor de IA direto. Para OpenAI, Anthropic e Mistral, envie a chave de administrador somente leitura: a Pleaxy faz uma leitura com ela e, só se isso funcionar, armazena-a criptografada, adiciona o cadastro de fornecedor do provedor aos seus fornecedores e retorna a conexão. Para a Snowflake, envie onde se autenticar: a Pleaxy gera um par de chaves e retorna a conexão como pending, com a chave pública a atribuir ao usuário de serviço; depois SyncAiProvider a verifica. Cinco verificações com falha por provedor em uma hora; depois disso, é preciso esperar. Exige acesso 'create' a fornecedores.

Erros

400 Bad Request - A validação falhou; a chave está ausente ou não é a chave de administrador desse provedor; o provedor não a aceitou (não autorizada, proibida, sem Admin API, ocupado ou inacessível, e nada foi salvo); cinco verificações com falha na última hora; ou o plano da região atingiu o limite de provedores.
404 Not Found - Provedor desconhecido, ou o conector dele não está ativado nesta região.
409 Conflict - O provedor já está conectado no espaço de trabalho.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/ai-providers

Requisição

POST /v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.buyer/ai-providers

{ "provider": "anthropic", "key": "sk-ant-admin01-…" }

Resposta · 201 Created

{
   "id": "aip_01k8q2m4xv7c9n3p5t6r8w0yzb",
   "provider": "anthropic",
   "accountLabel": "Northwind Labs",
   "keyHint": "f3Qa",
   "status": "connected",
   "connectedAt": "2026-10-30T09:12:44.000Z",
   "supplierConnectionId": "sc_01k8q2m5a1b2c3d4e5f6g7h8j9"
}

Sincronizar provedor de IA

Lê agora o custo e o uso de um provedor de IA.

POST/v1/workspaces/{regionId}/ai-providers/{id}/sync

Parâmetros

idstringObrigatório
O id da conexão com o provedor de IA.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Lê agora os relatórios de custo e uso de um provedor, em vez de esperar a execução diária, e retorna a conexão com o novo estado de sincronização. Para uma conexão da Snowflake em pending, primeiro verifica se o par de chaves se autentica e a marca como connected. Uma vez a cada 15 minutos por provedor. Não recebe corpo. Exige acesso 'create' a fornecedores ou acesso 'edit' a faturas.

Erros

400 Bad Request - Sincronizado há menos de 15 minutos, ou um par de chaves da Snowflake em pending ainda não se autentica (nada mudou).
404 Not Found - Essa conexão não existe no espaço de trabalho, ou o conector do provedor foi desativado.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/ai-providers/{id}/sync

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{id}/sync" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "id": "string",
   "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave",
   "status": "connected" | "pending",
   "lastSyncedAt": "string",
   "lastSyncStatus": "ok" | "error" | "throttled",
   "lastSyncError": "string"
}

Excluir provedor de IA

Desconecta um provedor de IA.

DELETE/v1/workspaces/{regionId}/ai-providers/{id}

Parâmetros

idstringObrigatório
O id da conexão com o provedor de IA.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Desconecta um provedor de IA direto: a conexão e a chave criptografada dela são excluídas, e fica registrado quem a desconectou. As linhas de IA já lidas ficam como histórico, e o cadastro de fornecedor permanece. Revogue também a chave no provedor (na Snowflake, remova a chave pública do usuário).

Sessão conectada com acesso 'edit' a fornecedores; uma chave de API recebe 403.

Erros

403 Forbidden - Quem chama é uma chave de API ou não tem 'edit' em fornecedores.
404 Not Found - Essa conexão não existe no espaço de trabalho.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.

DELETE /v1/workspaces/{regionId}/ai-providers/{id}

Requisição

curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{id}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

{
   "id": "string",
   "provider": "openai" | "anthropic" | "mistral" | "snowflake" | "openrouter" | "databricks" | "coreweave"
}

Adicionar provedor de IA como fornecedor

Adiciona um faturador de IA como fornecedor sem conectá-lo.

POST/v1/workspaces/{regionId}/ai-providers/{provider}/supplier

Parâmetros

providerstringObrigatório
Um de openai, anthropic, mistral, cohere, xai, openrouter, snowflake, databricks, coreweave, lambda, nebius, crusoe, cursor, github ou microsoft (ListAiInvoicers os lista).

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Adiciona um faturador de IA à sua lista de fornecedores a partir do cadastro que a Pleaxy cria previamente, sem conectar nada, para você poder emitir pedidos de compra para ele e registrar as faturas dele. Funciona para todo faturador de IA, inclusive os que a Pleaxy não consegue ler (os gastos deles vêm das faturas). Retorna o cadastro existente, se houver um, e conectar depois vincula ao mesmo cadastro. Não recebe corpo. Exige acesso 'create' a fornecedores.

Erros

404 Not Found - Faturador de IA desconhecido.
409 Conflict - Código SUPPLIER_ALREADY_LISTED: um fornecedor com esse nome já tem uma integração em andamento ou aprovada.
401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

POST /v1/workspaces/{regionId}/ai-providers/{provider}/supplier

Requisição

curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-providers/{provider}/supplier" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 201 Created

{
   "id": "string",
   "buyerOrgId": "string",
   "supplierName": "string",
   "aiProvider": "string",
   "status": "pending_invite" | "invited" | "in_progress" | "submitted" | "approved" | "rejected",
   "createdAt": "string"
}

Listar faturadores de IA

Lista os faturadores de IA que a Pleaxy cria previamente como fornecedores.

GET/v1/workspaces/{regionId}/ai-invoicers

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Os faturadores de IA para os quais a Pleaxy mantém um cadastro de fornecedor: os nomes, as entidades legais pelas quais faturam em cada região, as moedas em que cobram, se cobram por fatura, por créditos pré-pagos ou ambos, os domínios de onde vêm os e-mails de fatura deles, como a Pleaxy lê os gastos deles e se esse leitor está ativado na sua região (connectable). A Pleaxy mantém a lista; entidades legais e domínios são uma pista para o destinatário da cobrança, nunca uma verificação. Exige acesso 'view' a fornecedores ou a faturas.

Campos da resposta

legalEntitiesArray<object>
A entidade que fatura um comprador em cada região, default para toda região não listada, com o país dela.
credentialstring
Como a Pleaxy lê os gastos do faturador: admin_key (uma chave somente leitura que você cola), key_pair (um par de chaves que a Pleaxy gera) ou none (sem API de leitura; os gastos dele vêm das faturas).
shapestring
Em que as linhas dele são medidas: tokens, credits (Snowflake, Databricks) ou capacity (horas de GPU).
connectableboolean
Se CreateAiProvider pode conectá-lo agora nesta região.

Erros

401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.

GET /v1/workspaces/{regionId}/ai-invoicers

Requisição

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/ai-invoicers" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Resposta · 200 OK

[
   {
      "id": "string",
      "name": "string",
      "legalEntities": [ { "region": "us" | "eu" | "default", "name": "string", "country": "string" } ],
      "billingCurrencies": [ "string" ],
      "billing": [ "invoice" | "prepaid_credits" ],
      "senderDomains": [ "string" ],
      "credential": "admin_key" | "key_pair" | "none",
      "tier": "direct" | "data_platform" | "host" | "neocloud" | "seats",
      "shape": "tokens" | "credits" | "capacity" | "seats",
      "contactHint": "string",
      "connectable": boolean
   }
]