Listening e menções

Atualizar a triagem de correspondências do Listening

Atualizar indicadores locais de tratado/arquivado com expected_revision; não responde, oculta nem exclui conteúdo de origem. Exige agent:research.

POST /listening-api/results/set-state

Contrato revisado: 2026-11-03 · sha256:ab393e91e9b7f18a

Ler como Markdown Baixar contrato público Baixar OpenAPI

Visão geral

Atualizar indicadores locais de tratado/arquivado com expected_revision; não responde, oculta nem exclui conteúdo de origem. Exige agent:research.

Uma resposta HTTP bem-sucedida pode significar que uma requisição foi aceita, não concluída. Para trabalho em segundo plano, salve o ID retornado e consulte a mesma operação até terminar. Um post agendado ou aceito só está publicado quando a plataforma confirma; um timeout do cliente não comprova o resultado.

Autenticação e permissões

Classes de credenciais aceitas: user_session, delegated_oauth, personal_access_token
Capacidade delegada: agent:research
Função mínima no workspace: editor
Escopo de acesso: Recursos que este usuário tem autorização para acessar
Consentimento para todos os workspaces obrigatório: Não
Altera o estado: Sim
Quando a operação estiver concluída: committed Listening resource version or cancellation fence; no social platform writes

Um token só pode usar os direitos do seu proprietário. Cada requisição verifica participação no workspace, propriedade de recursos, workspaces selecionados e capacidades concedidas. Os perfis core e full mudam as ferramentas exibidas; não concedem acesso.

Campos da requisição

Obrigatório significa obrigatório dentro do objeto pai e da ramificação selecionada. Um filho obrigatório não torna obrigatório um pai opcional. As regras e nomes de campos abaixo são copiados do contrato.

Campos da requisição
Campo / ramificação	Tipo / obrigatório	Restrições
`$`	`object`Obrigatório no objeto pai	`additionalProperties: false`
`workspace_id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`mutation_id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`expected_revision`	`integer`Obrigatório no objeto pai	`maximum: 9007199254740991` `exclusiveMinimum: 0`
`handled`	`boolean`Opcional / item	—
`archived`	`boolean`Opcional / item	—

JSON Schema completo

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "mutation_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "expected_revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "handled": {
      "type": "boolean"
    },
    "archived": {
      "type": "boolean"
    }
  },
  "required": [
    "workspace_id",
    "mutation_id",
    "id",
    "expected_revision"
  ],
  "additionalProperties": false
}

Resposta e conclusão

Códigos HTTP de sucesso: 200. Quando a operação estiver concluída: committed Listening resource version or cancellation fence; no social platform writes.

Resposta e conclusão
Campo / ramificação	Tipo / obrigatório	Restrições
`$`	`object`Obrigatório no objeto pai	—
`result`	`object`Obrigatório no objeto pai	—
`result.id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`result.workspace_id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`result.stream_id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`result.run_id`	`string`Obrigatório no objeto pai	`format: "uuid"` `pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"`
`result.revision`	`integer`Obrigatório no objeto pai	`maximum: 9007199254740991` `exclusiveMinimum: 0`
`result.source`	`string`Obrigatório no objeto pai	`const: "hacker_news"`
`result.source_item_id`	`string`Obrigatório no objeto pai	`pattern: "^[1-9][0-9]{0,15}$"`
`result.canonical_url`	`string`Obrigatório no objeto pai	`pattern: "^https:\\/\\/news\\.ycombinator\\.com\\/item\\?id=[1-9][0-9]{0,15}$"`
`result.title`	`string \| null`Obrigatório no objeto pai	—
`result.title`anyOf 1	`string`Obrigatório no objeto pai	`maxLength: 500`
`result.title`anyOf 2	`null`Obrigatório no objeto pai	—
`result.excerpt`	`string \| null`Obrigatório no objeto pai	—
`result.excerpt`anyOf 1	`string`Obrigatório no objeto pai	`maxLength: 4000`
`result.excerpt`anyOf 2	`null`Obrigatório no objeto pai	—
`result.author`	`string \| null`Obrigatório no objeto pai	—
`result.author`anyOf 1	`string`Obrigatório no objeto pai	`maxLength: 100`
`result.author`anyOf 2	`null`Obrigatório no objeto pai	—
`result.published_at`	`string \| null`Obrigatório no objeto pai	—
`result.published_at`anyOf 1	`string`Obrigatório no objeto pai	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`result.published_at`anyOf 2	`null`Obrigatório no objeto pai	—
`result.retrieved_at`	`string`Obrigatório no objeto pai	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`result.source_checked_at`	`string`Obrigatório no objeto pai	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`result.expires_at`	`string`Obrigatório no objeto pai	`format: "date-time"` `pattern: "^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z\|([+-](?:[01]\\d\|2[0-3]):[0-5]\\d)))$"`
`result.availability`	`string`Obrigatório no objeto pai	`enum: ["available","removed","expired","unavailable"]`
`result.metrics`	`object`Obrigatório no objeto pai	—
`result.metrics.score`	`integer \| null`Obrigatório no objeto pai	—
`result.metrics.score`anyOf 1	`integer`Obrigatório no objeto pai	`minimum: -9007199254740991` `maximum: 9007199254740991`
`result.metrics.score`anyOf 2	`null`Obrigatório no objeto pai	—
`result.metrics.replies`	`integer \| null`Obrigatório no objeto pai	—
`result.metrics.replies`anyOf 1	`integer`Obrigatório no objeto pai	`minimum: 0` `maximum: 9007199254740991`
`result.metrics.replies`anyOf 2	`null`Obrigatório no objeto pai	—
`result.handled`	`boolean`Obrigatório no objeto pai	—
`result.archived`	`boolean`Obrigatório no objeto pai	—
`result.match_kind`	`string`Obrigatório no objeto pai	`const: "literal_query_match"`
`result.coverage`	`string`Obrigatório no objeto pai	`const: "partial_indexed_sample"`
`result.sentiment`	`null`Obrigatório no objeto pai	—

JSON Schema completo

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "result": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "workspace_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "stream_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "run_id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "revision": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "source": {
          "type": "string",
          "const": "hacker_news"
        },
        "source_item_id": {
          "type": "string",
          "pattern": "^[1-9][0-9]{0,15}$"
        },
        "canonical_url": {
          "type": "string",
          "pattern": "^https:\\/\\/news\\.ycombinator\\.com\\/item\\?id=[1-9][0-9]{0,15}$"
        },
        "title": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ]
        },
        "excerpt": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000
            },
            {
              "type": "null"
            }
          ]
        },
        "author": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 100
            },
            {
              "type": "null"
            }
          ]
        },
        "published_at": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        },
        "retrieved_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        "source_checked_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        "expires_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
          "format": "date-time"
        },
        "availability": {
          "type": "string",
          "enum": [
            "available",
            "removed",
            "expired",
            "unavailable"
          ]
        },
        "metrics": {
          "type": "object",
          "properties": {
            "score": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            },
            "replies": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "score",
            "replies"
          ]
        },
        "handled": {
          "type": "boolean"
        },
        "archived": {
          "type": "boolean"
        },
        "match_kind": {
          "type": "string",
          "const": "literal_query_match"
        },
        "coverage": {
          "type": "string",
          "const": "partial_indexed_sample"
        },
        "sentiment": {
          "type": "null"
        }
      },
      "required": [
        "id",
        "workspace_id",
        "stream_id",
        "run_id",
        "revision",
        "source",
        "source_item_id",
        "canonical_url",
        "title",
        "excerpt",
        "author",
        "published_at",
        "retrieved_at",
        "source_checked_at",
        "expires_at",
        "availability",
        "metrics",
        "handled",
        "archived",
        "match_kind",
        "coverage",
        "sentiment"
      ]
    }
  },
  "required": [
    "result"
  ]
}

Erros e repetições seguras

Confira o status HTTP e o corpo da resposta. Um erro de validação 400 pode conter ZodError; erros do handler usam os campos error, message e code. Guarde request_id ou x-request-id para diagnóstico, sem credenciais. Corrija erros de acesso 401/403 antes de tentar novamente e siga Retry-After para 429. Se uma gravação for incerta ou retornar 5xx, consulte primeiro o resultado existente. Reutilize uma chave de idempotência somente quando houver suporte; o comportamento de repetição varia por operação e não garante entrega exatamente uma vez.

Guia de solução de problemas

Exemplos

Estes exemplos usam valores fictícios verificados conforme os schemas. Substitua os IDs por aqueles que você tem autorização para usar, a mídia por ativos prontos e as datas pelo horário de publicação confirmado. Confira a elegibilidade da conta antes de enviar uma gravação. Esta página não envia requisições de API.

Defina SOSOAPI_ACCESS_TOKEN no servidor como uma credencial aceita por esta operação e mantenha-a fora do código do navegador. Para agentes de IA, use sosoapi auth login para entrar pelo navegador e deixe a CLI renovar suas credenciais.

request.json

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "id": "30000000-0000-4000-8000-000000000005",
  "mutation_id": "40000000-0000-4000-8000-000000000003",
  "expected_revision": 1,
  "handled": true
}

cURL

curl --request POST \
  "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/listening-api/results/set-state" \
  -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

JavaScript

// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/listening-api/results/set-state", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
  body: JSON.stringify({
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "id": "30000000-0000-4000-8000-000000000005",
  "mutation_id": "40000000-0000-4000-8000-000000000003",
  "expected_revision": 1,
  "handled": true
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.

CLI

npx sosoapi api post /listening-api/results/set-state < request.json

Exemplo de resposta sintética

{
  "result": {
    "id": "30000000-0000-4000-8000-000000000005",
    "workspace_id": "11111111-1111-4111-8111-111111111111",
    "stream_id": "30000000-0000-4000-8000-000000000004",
    "run_id": "30000000-0000-4000-8000-000000000009",
    "revision": 2,
    "source": "hacker_news",
    "source_item_id": "9999999999999999",
    "canonical_url": "https://news.ycombinator.com/item?id=9999999999999999",
    "title": null,
    "excerpt": null,
    "author": null,
    "published_at": null,
    "retrieved_at": "2099-01-15T09:00:00Z",
    "source_checked_at": "2099-01-15T09:00:00Z",
    "expires_at": "2099-01-16T09:00:00Z",
    "availability": "unavailable",
    "metrics": {
      "score": null,
      "replies": null
    },
    "handled": true,
    "archived": false,
    "match_kind": "literal_query_match",
    "coverage": "partial_indexed_sample",
    "sentiment": null
  }
}

MCP: sosoapi_listening_results_set_state

Todas as operações da API Autenticação e permissões

Preferências de privacidade

Funções necessárias

Análises opcionais de uso

Permitir também a reprodução de sessões neste site público

Atualizar a triagem de correspondências do Listening

Visão geral

Autenticação e permissões

Campos da requisição

Resposta e conclusão

Erros e repetições seguras

Exemplos

request.json

cURL

JavaScript

CLI

Exemplo de resposta sintética

Atualizar a triagem de correspondências do Listening

Visão geral

Autenticação e permissões

Campos da requisição

Resposta e conclusão

Erros e repetições seguras

Exemplos

request.json

cURL

JavaScript

CLI

Exemplo de resposta sintética

Ferramentas e guias relacionados