API

API

Marque e detecte arquivos com a API do Markedfile. Disponível nos planos Business e Enterprise.

Chaves de API

O proprietário de um espaço de trabalho Business ou Enterprise cria e revoga as chaves nas configurações do espaço. Uma chave é exibida uma única vez. O Markedfile armazena um hash SHA-256, um prefixo curto e o nome. Ele não armazena o segredo.

Uma chave pertence a exatamente um espaço de trabalho. Ela só atua nele, com os limites do plano desse espaço. Espaços pessoais não têm chaves. Um membro que não é o proprietário não pode criá-las nem revogá-las.

Se o espaço de trabalho perder o plano Business ou Enterprise ativo, todas as chaves param de funcionar imediatamente, inclusive durante os 30 dias em que os arquivos existentes ainda podem ser detectados no aplicativo. Ao voltar para o Business ou o Enterprise, as chaves que não foram revogadas voltam a funcionar.

Autenticação

Envie o segredo no cabeçalho Authorization como um token Bearer. Estas rotas não usam cookie de sessão. Um navegador em outro site é recusado.

Auditoria

Criar, revogar, marcar e detectar gravam uma linha de auditoria que o proprietário do espaço de trabalho pode ler. A linha não inclui o arquivo.

MCP remoto

O MCP remoto exige um plano Business ou Enterprise ativo no espaço que concede.

Cole o URL do conector num cliente que fale MCP por Streamable HTTP. O Markedfile inicia sessão com a mesma conta, incluindo SSO e um autenticador, e pergunta qual espaço a aplicação pode usar. https://markedfile.com/api/mcp

O cliente regista-se sozinho, usa PKCE e recebe um token de acesso de curta duração para esse espaço. Revogue a ligação junto das chaves de API. Não há uma CLI de ficheiros.

Claude

  1. Em claude.ai, abra Definições, depois Conectores, e adicione um conector personalizado. No Claude Desktop, abra Definições, depois Conectores, e adicione um conector personalizado.
  2. Cole o URL do conector. Deixe o cliente concluir o início de sessão no navegador.
  3. Inicie sessão no Markedfile, com SSO ou autenticador se a conta os usar, e escolha o espaço.

Cursor

  1. Abra as definições do Cursor, depois MCP, e adicione um servidor.
  2. Escolha Streamable HTTP e cole o URL do conector.
  3. Conclua o início de sessão no navegador e escolha o espaço. O Cursor guarda o token de atualização localmente.

VS Code

  1. No VS Code, execute MCP: Add Server na paleta de comandos, ou adicione um servidor HTTP em mcp.json.
  2. Defina o tipo como http e o URL como o do conector.
  3. Conclua o início de sessão no navegador e escolha o espaço.

ChatGPT

  1. No ChatGPT, abra Definições e depois Conectores. O modo de programador também pode adicionar um conector ou uma app personalizada.
  2. Adicione o URL do conector e inicie a sessão.
  3. Inicie sessão no Markedfile e escolha o espaço. Marcar e detetar só funcionam enquanto esse espaço for Business ou Enterprise.

Grok Bot

  1. No Grok Bot, peça ao seu bot no chat para adicionar um conector com o URL https://markedfile.com/api/mcp.
  2. Autorize a sua conta Markedfile no ecrã OAuth que abrir.

Endpoints

POST/api/v1/mark

Marca um arquivo e devolve a cópia marcada. O corpo é multipart/form-data.

Autenticação

Authorization: Bearer mf_…

Envie este cabeçalho. Não há cookie de sessão. O curl e outros clientes de servidor são aceitos. Um navegador em outro site é recusado.

Parâmetros

NomeTipoObrigatórioDescrição
filefileSimO arquivo a ser marcado. Business aceita até 100 MB, 500 páginas de PDF e vídeo de até 10 minutos. No Enterprise, o tamanho do arquivo, as páginas do PDF, a duração do vídeo e o tamanho do arquivo de vídeo são Sob medida. O tamanho do envio, a duração do vídeo e o número de páginas do PDF seguem o plano do espaço de trabalho.
identifierstringSimDe 1 a 32 caracteres, sem caracteres de controle. É o rótulo que você vê se essa cópia for detectada depois. Ele não é gravado no arquivo como texto legível.

Requisição

curl -X POST https://markedfile.com/api/v1/mark \
  -H "Authorization: Bearer mf_…" \
  -F "file=@contract.pdf" \
  -F "identifier=northwind"

Resposta

{
  "file": "JVBERi0xLjQK…",
  "mime": "application/pdf",
  "name": "contract.pdf",
  "kind": "pdf",
  "layers": [
    {
      "name": "Metadata",
      "detail": "Authenticated workspace reference; the identifier stays on the server",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "remaining": 1
}

file são os bytes marcados em base64. mime, name e kind descrevem o download. layers lista as camadas que foram aplicadas. Quando o plano não tem limite de arquivos ativos, remaining é o número de arquivos ativos depois desta marca. Quando tem limite, remaining é quantas marcas novas ainda restam. Business e Enterprise não têm limite de arquivos ativos. É a exclusão de um arquivo que encerra a detecção.

Erros

O texto do campo error no corpo JSON está em inglês.

StatusDescrição
400O arquivo está vazio, ou o identificador está vazio, tem mais de 32 caracteres ou contém um caractere de controle.
401A chave está ausente, foi revogada ou é desconhecida. O corpo JSON inclui "code": "api-key".
403O espaço de trabalho não tem mais um plano Business ou Enterprise ativo (o corpo inclui "code": "enterprise"), ou o navegador enviou uma requisição cross-site ou same-site.
413O arquivo passa do limite de envio do plano, ou o PDF tem mais páginas do que o plano permite.
422Não foi possível processar o arquivo.
503O servidor está ocupado, ou a marcação está pausada para manutenção.
429Esta chave marcou mais de 40 arquivos no minuto atual.

Limite de requisições

40 requisições por minuto para esta chave. O contador fica no banco de dados do produto e continua valendo depois de uma reinicialização.

POST/api/v1/detect

Verifica um arquivo no espaço de trabalho desta chave. O corpo é multipart/form-data.

Autenticação

Authorization: Bearer mf_…

Envie este cabeçalho. Não há cookie de sessão. O curl e outros clientes de servidor são aceitos. Um navegador em outro site é recusado.

Parâmetros

NomeTipoObrigatórioDescrição
filefileSimO arquivo a ser verificado. A correspondência é procurada só no espaço de trabalho desta chave. Um arquivo marcado em outro espaço de trabalho não é identificado. Um espaço Business ou Enterprise ativo também pode verificar um arquivo de vídeo. A captura de tela de um único quadro é verificada como imagem.

Requisição

curl -X POST https://markedfile.com/api/v1/detect \
  -H "Authorization: Bearer mf_…" \
  -F "file=@leaked.pdf"

Resposta

{
  "id": "northwind",
  "confidence": 0.95,
  "layers": [
    {
      "name": "Metadata",
      "hit": true,
      "detail": "Authenticated metadata matched this workspace",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "notes": [
    "Confidence is 99% for an exact file or when an authenticated mark agrees with another mark. A visual match alone stays lower, and weak bit agreement stays far from a high score."
  ]
}

id é o identificador que você definiu quando essa cópia foi marcada, ou null quando este espaço de trabalho não tem correspondência. confidence é de 99% para um arquivo exato ou quando uma marca autenticada concorda com outra marca. Uma correspondência apenas visual fica mais baixa. layers lista as camadas, e hit é true nas que concordaram. notes descreve o que a verificação fez. Um arquivo excluído não é identificado.

Erros

O texto do campo error no corpo JSON está em inglês.

StatusDescrição
400O arquivo está vazio.
401A chave está ausente, foi revogada ou é desconhecida. O corpo JSON inclui "code": "api-key".
403O espaço de trabalho não tem mais um plano Business ou Enterprise ativo (o corpo inclui "code": "enterprise"), ou o navegador enviou uma requisição cross-site ou same-site.
413O arquivo passa do limite de envio do plano, ou o PDF tem mais páginas do que o plano permite.
422Não foi possível processar o arquivo.
503O servidor está ocupado, ou a marcação está pausada para manutenção.
429Esta chave fez mais de 80 detecções no minuto atual.

Limite de requisições

80 requisições por minuto para esta chave. O contador fica no banco de dados do produto e continua valendo depois de uma reinicialização.