Referência da API Keymatic

Gerada do OpenAPI publicado em /api/instagram/openapi.json. 28 operações, base /api/instagram.

Convenções

Envie Authorization: Bearer $KEYMATIC_API_KEY. As respostas têm Cache-Control: no-store.
Os exemplos usam uma chave de conta. Com OAuth de várias contas, liste /contas e informe X-Keymatic-Conta-Id nas operações de uma conta. A ausência do alvo devolve conta_necessaria.
Escritas devolvem 202 com uma operação; veja Idempotência e operações.
Erros usam {"erro": {"codigo", "mensagem"}}; veja Erros.
Operações marcadas com “requer permissão Meta” dependem de App Review para contas externas.

API Keymatic para Instagram

Dados e ações da conta Instagram escolhida pela chave ou pelo alvo da sessão OAuth. Bearer km_api_, km_mcp_ ou access token OAuth do MCP.

Listar Instagrams autorizados nesta credencial

GET/contas

Permissão ler

Snapshot do consentimento, sem consulta à Meta. exige_conta indica que as operações precisam de X-Keymatic-Conta-Id; novos Instagrams não entram automaticamente.

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/contas" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Ler o perfil do Instagram da chave

GET/perfil

Permissão ler

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/perfil" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Consultar plano, uso e limites

GET/uso

Permissão ler

Não reserva operação da franquia.

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/uso" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Listar publicações

GET/publicacoes

Permissão ler

Paginação por cursor; limite de 1 a 50.

Consulta

cursorstring | null
limiteinteger | null

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/publicacoes" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Publicar ou agendar

POST/publicacoes

Permissão publicar
Exige Idempotency-Key
Requer permissão Meta instagram_business_content_publish

Formatos imagem, reel, carrossel (2–10 imagens), story_imagem e story_video. Agenda com fuso, até 30 dias. Devolve 202 com a operação; acompanhe por GET /operacoes/{operacao_id}.

Cabeçalhos

X-Keymatic-Conta-Idstring | null
Idempotency-Keystring | nullobrigatório: Obrigatório nas escritas; ausência retorna HTTP 428.

Corpo JSON · ConteudoPublicacao

formato"imagem" | "reel" | "carrossel" | "story_imagem" | "story_video"obrigatório
arquivosstring[]obrigatório: 1–10 itens
legendastring: até 2200 caracteres
executar_emstring (date-time) | null

Respostas

202 operação assíncrona: operacao_id, estado, executar_em, resultado, erro.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/publicacoes" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Idempotency-Key: publicacoes-pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
  "formato": "imagem",
  "arquivos": [
    "<url-de-POST-/midias/importacoes>"
  ],
  "legenda": "Coleção nova no ar",
  "executar_em": "2026-11-10T12:00:00-03:00"
}'

Ler comentários de uma publicação

GET/publicacoes/{media_id}/comentarios

Permissão ler

Caminho

media_idstringobrigatório

Consulta

cursorstring | null
limiteinteger | null

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/publicacoes/<media_id>/comentarios" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Métricas de uma publicação

GET/publicacoes/{media_id}/insights

Permissão ler
Requer permissão Meta instagram_business_manage_insights

Caminho

media_idstringobrigatório

Consulta

metricasstring | null

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/publicacoes/<media_id>/insights" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Métricas do perfil

GET/insights

Permissão ler
Requer permissão Meta instagram_business_manage_insights

Intervalo de até 30 dias, datas ISO com fuso.

Consulta

desdestringobrigatório
atestringobrigatório
metricasstring | null

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/insights?desde=<desde>&ate=<ate>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Importar mídia por URL

POST/midias/importacoes

Permissão publicar

HTTPS público. Imagem JPEG/PNG/WebP até 12 MiB; MP4 até 100 MB. Devolve 201 com a URL Keymatic a usar em POST /publicacoes. Sem idempotência: guarde o resultado.

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Corpo JSON · ImportarArquivo

urlstringobrigatório: 8–2048 caracteres
tipo"imagem" | "video"obrigatório

Respostas

201 recurso criado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/midias/importacoes" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://cdn.seu-produto.com/fotos/colecao.jpg",
  "tipo": "imagem"
}'

Consultar uma operação

GET/operacoes/{operacao_id}

Permissão ler

Não reserva operação da franquia.

Caminho

operacao_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/operacoes/<operacao_id>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Cancelar um agendamento

POST/operacoes/{operacao_id}/cancelamento

Permissão publicar

Só publicação ainda no estado agendada.

Caminho

operacao_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/operacoes/<operacao_id>/cancelamento" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Listar mensagens recebidas

GET/mensagens/recebidas

Permissão mensagens

Até 50 eventos de webhook das últimas 24 h.

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/mensagens/recebidas" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Responder uma mensagem do Direct

POST/mensagens/recebidas/{evento_id}/respostas

Permissão responder + mensagens
Exige Idempotency-Key

Só mensagem recebida comprovada por webhook, dentro de 24 h e sem opt-out. Não inicia conversa. Devolve 202 com a operação; acompanhe por GET /operacoes/{operacao_id}.

Caminho

evento_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null
Idempotency-Keystring | nullobrigatório: Obrigatório nas escritas; ausência retorna HTTP 428.

Corpo JSON · TextoDeResposta

textostringobrigatório: 1–1000 caracteres

Respostas

202 operação assíncrona: operacao_id, estado, executar_em, resultado, erro.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/mensagens/recebidas/<evento_id>/respostas" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Idempotency-Key: mensagens-recebidas-evento-id-respostas-pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
  "texto": "<texto>"
}'

Listar conversas

GET/conversas

Permissão mensagens

Consulta

cursorstring | null
limiteinteger | null

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/conversas" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Ler uma conversa

GET/conversas/{igsid}

Permissão mensagens

Caminho

igsidstringobrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/conversas/<igsid>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Ler uma mensagem

GET/mensagens/{mensagem_id}

Permissão mensagens

Caminho

mensagem_idstringobrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/mensagens/<mensagem_id>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Responder um comentário

POST/comentarios/{comment_id}/respostas

Permissão responder
Exige Idempotency-Key

Devolve 202 com a operação; acompanhe por GET /operacoes/{operacao_id}.

Caminho

comment_idstringobrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null
Idempotency-Keystring | nullobrigatório: Obrigatório nas escritas; ausência retorna HTTP 428.

Corpo JSON · RespostaAoComentario

textostringobrigatório: 1–1000 caracteres
media_idstringobrigatório: formato ^[0-9]{1,64}$

Respostas

202 operação assíncrona: operacao_id, estado, executar_em, resultado, erro.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/comentarios/<comment_id>/respostas" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Idempotency-Key: comentarios-comment-id-respostas-pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
  "texto": "<texto>",
  "media_id": "<media_id>"
}'

Ocultar ou reexibir um comentário

POST/comentarios/{comment_id}/ocultacao

Permissão moderar
Exige Idempotency-Key

Devolve 202 com a operação; acompanhe por GET /operacoes/{operacao_id}.

Caminho

comment_idstringobrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null
Idempotency-Keystring | nullobrigatório: Obrigatório nas escritas; ausência retorna HTTP 428.

Corpo JSON · ModeracaoDoComentario

media_idstringobrigatório: formato ^[0-9]{1,64}$
ocultarbooleanobrigatório

Respostas

202 operação assíncrona: operacao_id, estado, executar_em, resultado, erro.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/comentarios/<comment_id>/ocultacao" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Idempotency-Key: comentarios-comment-id-ocultacao-pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
  "media_id": "<media_id>",
  "ocultar": true
}'

Listar regras de resposta automática

GET/automacoes

Permissão ler

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/automacoes" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Criar regra de resposta automática

POST/automacoes

Permissão responder
Exige Idempotency-Key

Regra simples por palavra-chave, não um agente generativo. retroativo é false por padrão.

Cria regra simples que o motor existente executa nos próximos comentários. Idempotente pela chave no razão de operações da credencial (mesma franquia do MCP). Retroativo só com `retroativo: true`.

Cabeçalhos

X-Keymatic-Conta-Idstring | null
Idempotency-Keystring | nullobrigatório: Obrigatório nas escritas; ausência retorna HTTP 428.

Corpo JSON · RegraSimplesNova

nomestringobrigatório: 1–120 caracteres
tipo"dm" | "comentario": padrão "dm"
palavras_chavestring[]obrigatório: 1–20 itens
modo_match"contem" | "palavra_inteira" | "exato": padrão "contem"
media_idsstring[]: até 50 itens
mensagem_dmstring | null
responder_comentarioboolean: padrão false
respostas_comentariostring[]: até 5 itens
ativaboolean: padrão true
retroativoboolean: padrão false

Respostas

201 recurso criado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/automacoes" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Idempotency-Key: automacoes-pedido-123" \
  -H "Content-Type: application/json" \
  -d '{
  "nome": "Enviar detalhes",
  "tipo": "dm",
  "palavras_chave": [
    "KEY"
  ],
  "modo_match": "palavra_inteira",
  "media_ids": [],
  "mensagem_dm": "Olá! Aqui estão os detalhes que você pediu.",
  "responder_comentario": true,
  "respostas_comentario": [
    "Enviei no Direct."
  ],
  "ativa": true,
  "retroativo": false
}'

Ler uma regra

GET/automacoes/{automacao_id}

Permissão ler

Caminho

automacao_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/automacoes/<automacao_id>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Editar ou pausar uma regra

PATCH/automacoes/{automacao_id}

Permissão responder

Envie a versao_esperada lida no GET; conflito devolve 409.

Edita ou pausa. `versao_esperada` impede sobrescrever edição concorrente.

Caminho

automacao_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Corpo JSON · RegraSimplesEdicao

versao_esperadaintegerobrigatório: mínimo 0
nomestring | null: 1–120 caracteres
palavras_chavestring[] | null: 1–20 itens
modo_match"contem" | "palavra_inteira" | "exato" | null
media_idsstring[] | null: até 50 itens
mensagem_dmstring | null
responder_comentarioboolean | null
respostas_comentariostring[] | null: até 5 itens
ativaboolean | null

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X PATCH "https://ig.keymatic.com.br/api/instagram/automacoes/<automacao_id>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "versao_esperada": 2,
  "ativa": false
}'

Excluir uma regra

DELETE/automacoes/{automacao_id}

Permissão responder

Caminho

automacao_idstring (uuid)obrigatório

Cabeçalhos

X-Keymatic-Conta-Idstring | null

Respostas

204 sem corpo.
422 entrada fora do esquema. Demais erros em Erros.

curl -X DELETE "https://ig.keymatic.com.br/api/instagram/automacoes/<automacao_id>" \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Conexão de parceiro

Contas que os clientes do seu produto conectaram pelo onboarding hospedado. Somente com a chave de projeto km_proj_, no backend.

Abrir sessão de conexão hospedada

POST/conexoes/sessoes

Chave de projeto km_proj_

Devolve a url para onde o CRM redireciona o cliente final. Ticket de uso único, 10 min.

Corpo JSON · NovaSessao

url_retornostringobrigatório: 8–500 caracteres
statestringobrigatório: formato ^[A-Za-z0-9._~:\-]{1,200}$
permissoesstring[] | null: até 5 itens

Respostas

201 recurso criado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/conexoes/sessoes" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url_retorno": "https://app.seu-crm.com/integracoes/keymatic/retorno",
  "state": "<nonce-do-crm>",
  "permissoes": [
    "ler",
    "mensagens"
  ]
}'

Trocar o code pela chave da conta

POST/conexoes/codigos

Chave de projeto km_proj_

Uso único, 5 min. Sem retry automático: repetir devolve 409 code_invalido e revoga a chave emitida.

Corpo JSON · TrocaDeCode

codestringobrigatório: 10–200 caracteres

Respostas

201 recurso criado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/conexoes/codigos" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "<code-do-callback>"
}'

Listar contas concedidas ao projeto

GET/conexoes/contas

Chave de projeto km_proj_

Respostas

200 JSON com o resultado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X GET "https://ig.keymatic.com.br/api/instagram/conexoes/contas" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY"

Emitir nova chave para uma conta

POST/conexoes/contas/{conta_id}/credenciais

Chave de projeto km_proj_

Só para conta concedida a este projeto; senão 404.

Caminho

conta_idstring (uuid)obrigatório

Corpo JSON · NovaChaveDaConta

revogar_anterioresboolean: padrão false

Respostas

201 recurso criado.
422 entrada fora do esquema. Demais erros em Erros.

curl -X POST "https://ig.keymatic.com.br/api/instagram/conexoes/contas/<conta_id>/credenciais" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "revogar_anteriores": false
}'

Revogar a concessão de uma conta

DELETE/conexoes/contas/{conta_id}

Chave de projeto km_proj_

Revoga a concessão e as chaves filhas.

Caminho

conta_idstring (uuid)obrigatório

Respostas

204 sem corpo.
422 entrada fora do esquema. Demais erros em Erros.

curl -X DELETE "https://ig.keymatic.com.br/api/instagram/conexoes/contas/<conta_id>" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY"