Desenvolvedores

Cotas, filas e proteção

A API está disponível para o plano Avançado e superusuários. Toda chamada de compressão pela API consome as mesmas cotas da conta: limite de tokens por arquivo, tokens mensais, quantidade mensal de processamentos e créditos TranscriptAPI quando a URL for YouTube com chave do sistema.

O endpoint POST /api/compress enfileira o documento e retorna job_id. Para acompanhar, use GET /api/documents/{id} ou liste com status=queued, status=processing ou status=all. O servidor também aplica rate limit: 120 requisições por minuto e 60 envios por hora por usuário; superusuários têm limites maiores.

O que a API permite

A API serve para integrar a biblioteca ProseFold a agentes, chatbots e sistemas externos. Ela lê documentos já processados sem chamar Gemini e envia novos conteúdos para a fila de compressão quando necessário.

A API não expõe administração, cobrança, exclusão de documentos nem arquivos de outros usuários. Também ainda não retorna arquivo anexado via openaiFileResponse; a leitura atual é por JSON paginado. Se o original for PDF, DOCX ou XLSX, leia type=markdown para acessar a versão textual convertida.

Instruções do GPT

Cole este texto nas instruções do GPT para que ele saiba quando listar documentos, quando ler o ProseFolded e como lidar com paginação.

Você tem acesso à biblioteca ProseFold do usuário por meio da Action.

Antes de analisar documentos, use listProseFoldDocuments para verificar o que já existe na biblioteca do usuário. Use getProseFoldDocument para conferir progresso, variantes disponíveis, tokens, tamanho e compressão.

Para ler conteúdo, prefira getProseFoldDocumentContent com type=prosefold. Use type=markdown para a conversão próxima do original e type=cypher ou type=minified_cypher quando o usuário pedir contexto mais compacto.

Se a resposta vier com has_more=true, continue chamando a próxima página até ter contexto suficiente. Não invente conteúdo que não veio da API.

Você também pode enviar novas entradas ao ProseFold pela Action. Use compressTextWithProseFold com text, markdown ou url. Para página pública, PDF público com texto selecionável ou YouTube, envie a URL para o ProseFold buscar, converter e enfileirar.

Depois de enviar algo para compressão, informe o job_id e acompanhe com getProseFoldDocument ou listProseFoldDocuments usando status=queued, processing ou all. Quando estiver completo, leia com getProseFoldDocumentContent.

Respeite os limites da conta: a Action usa as mesmas cotas de plano, tokens, transcripts YouTube e rate limits do usuário.

Action para GPT

No GPT Builder, abra Configure, crie uma nova Action, escolha autenticação por API key em modo Bearer, cole o token pf_... do usuário e depois cole o schema abaixo. Se preferir importar por URL, use https://prosefold.narra.com.br/openapi.json.

O schema de Actions trabalha com JSON: envie text, markdown ou url. Para PDF público, envie apenas a URL do PDF. Upload de arquivo local usa multipart e é voltado para integrações REST, não para o fluxo principal de Actions. A escolha entre ProseFolded, Cypher ou Minified acontece depois, na leitura com type.

Limite do ChatGPT para arquivos retornados por Actions: até 10 arquivos por resposta, cada arquivo com até 10 MB. Imagens e vídeos não são aceitos como arquivo retornado; se a Action devolver uma URL, o ChatGPT precisa conseguir baixar o arquivo em até 10 segundos.

Mesmo quando o ChatGPT não puder enviar um arquivo grande pela Action, ele pode enviar uma url para o ProseFold buscar e processar páginas públicas, PDFs públicos com texto selecionável e vídeos do YouTube. YouTube usa TranscriptAPI e consome créditos do plano.

A Action lê documentos por JSON paginado. Entrega direta de arquivo anexado à conversa via openaiFileResponse ainda não está disponível nesta versão da API.

{
    "openapi": "3.1.0",
    "info": {
        "title": "ProseFold Library API",
        "version": "1.0.0",
        "description": "Acesso por token à biblioteca ProseFold do usuário: listar documentos, ler variantes em Markdown compacto e enviar textos, Markdown ou URLs públicas para compressão semântica."
    },
    "servers": [
        {
            "url": "https://prosefold.narra.com.br"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "ProseFold API token"
            }
        },
        "schemas": {
            "Document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "source_type": {
                        "type": "string"
                    },
                    "source_url": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "compression_level": {
                        "type": "string"
                    },
                    "compression_label": {
                        "type": "string"
                    },
                    "input_tokens": {
                        "type": "integer"
                    },
                    "output_tokens": {
                        "type": "integer"
                    },
                    "original_kb": {
                        "type": "string"
                    },
                    "prosefold_kb": {
                        "type": "string"
                    },
                    "compression_percent": {
                        "type": "string"
                    },
                    "available_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/api/me": {
            "get": {
                "operationId": "getProseFoldAccount",
                "summary": "Confere a conta autenticada no ProseFold.",
                "description": "Use para confirmar usuário, plano e se a API está habilitada antes de iniciar fluxos avançados.",
                "responses": {
                    "200": {
                        "description": "Conta autenticada."
                    },
                    "401": {
                        "description": "Token inválido."
                    }
                }
            }
        },
        "/api/documents": {
            "get": {
                "operationId": "listProseFoldDocuments",
                "summary": "Lista documentos da biblioteca do usuário.",
                "description": "Use primeiro para verificar arquivos já presentes. Filtre por status, nome ou URL antes de ler ou pedir confirmação.",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "complete",
                                "queued",
                                "processing",
                                "failed",
                                "all"
                            ],
                            "default": "complete"
                        },
                        "description": "Use complete para listar apenas documentos prontos para leitura."
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Filtro textual por nome ou URL de origem."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lista de documentos."
                    }
                }
            }
        },
        "/api/documents/{id}": {
            "get": {
                "operationId": "getProseFoldDocument",
                "summary": "Obtém metadados de um documento.",
                "description": "Use para conferir progresso, tokens, tamanho, compressão e variantes antes de ler o conteúdo.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Documento encontrado."
                    },
                    "404": {
                        "description": "Documento não encontrado."
                    }
                }
            }
        },
        "/api/documents/{id}/content": {
            "get": {
                "operationId": "getProseFoldDocumentContent",
                "summary": "Lê o conteúdo textual de uma variante do documento.",
                "description": "Use para ler ProseFolded, Cypher, Minified ou Markdown em páginas. Continue se has_more=true.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "prosefold",
                                "cypher",
                                "minified",
                                "minified_cypher",
                                "markdown",
                                "original"
                            ],
                            "default": "prosefold"
                        },
                        "description": "Prefira prosefold para leitura semântica. Use markdown para o documento convertido e minified_cypher para contexto extremamente compacto."
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "page_size_chars",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1000,
                            "maximum": 60000,
                            "default": 24000
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Conteúdo textual paginado."
                    },
                    "413": {
                        "description": "Arquivo grande demais para retorno por JSON."
                    },
                    "409": {
                        "description": "Documento ainda em processamento."
                    },
                    "415": {
                        "description": "Original binário; use markdown."
                    }
                }
            }
        },
        "/api/compress": {
            "post": {
                "operationId": "compressTextWithProseFold",
                "summary": "Envia texto, Markdown ou URL para compressão semântica.",
                "description": "Use para enfileirar texto, Markdown, página pública, PDF público textual ou YouTube. Retorna job_id para acompanhar.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "description": "Envie markdown, text ou url. Para PDF público e YouTube, envie a URL; não anexe arquivo.",
                                "properties": {
                                    "markdown": {
                                        "type": "string",
                                        "description": "Markdown já extraído ou preparado para compressão."
                                    },
                                    "text": {
                                        "type": "string",
                                        "description": "Texto bruto que o ProseFold tratará como Markdown simples."
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "URL pública de página, PDF ou vídeo do YouTube para o ProseFold buscar, converter e comprimir."
                                    },
                                    "compression_level": {
                                        "type": "string",
                                        "enum": [
                                            "high",
                                            "ultra"
                                        ],
                                        "default": "high"
                                    },
                                    "gemini_key_source": {
                                        "type": "string",
                                        "enum": [
                                            "system",
                                            "own"
                                        ],
                                        "default": "system"
                                    },
                                    "transcriptapi_key_source": {
                                        "type": "string",
                                        "enum": [
                                            "system",
                                            "own"
                                        ],
                                        "default": "system"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Documento enfileirado para processamento."
                    },
                    "403": {
                        "description": "Plano sem acesso à API ou conta suspensa."
                    },
                    "422": {
                        "description": "Entrada inválida, formato não suportado ou cota excedida."
                    },
                    "429": {
                        "description": "Rate limit excedido."
                    }
                }
            }
        }
    }
}

Claude e MCP

No Claude, o equivalente arquitetural mais próximo de Actions é o MCP, Model Context Protocol. Diferente do GPT Builder, o Claude não consome diretamente este schema OpenAPI como uma Action; ele se conecta a um servidor MCP local ou remoto, e esse servidor chama a API REST do ProseFold.

O ProseFold já fornece a API necessária. O MCP é uma camada de ponte que transforma ferramentas Claude em chamadas como listar biblioteca, ler ProseFolded, ler Cypher, ler Minified e enviar texto para compressão.

prosefold_list_documents
prosefold_get_document
prosefold_get_document_content
prosefold_compress_text
prosefold_compress_url

{
  "mcpServers": {
    "prosefold": {
      "command": "node",
      "args": ["/caminho/prosefold-mcp/server.js"],
      "env": {
        "PROSEFOLD_API_TOKEN": "pf_SEU_TOKEN"
      }
    }
  }
}

Use MCP quando quiser que Claude Desktop, Claude Code, Cursor ou outro cliente compatível descubra ferramentas ProseFold. Use GPT Actions quando estiver no ChatGPT e quiser colar o OpenAPI diretamente.

n8n, Zapier e MindStudio

Essas plataformas acessam o ProseFold pela API HTTP. Use sempre HTTPS, envie o token no header Authorization: Bearer pf_SEU_TOKEN e escolha o endpoint conforme a automação: listar biblioteca, ler documento ou enfileirar uma nova compressão.

Method: GET
URL: https://prosefold.narra.com.br/api/documents
Headers:
  Authorization: Bearer pf_SEU_TOKEN

POST https://prosefold.narra.com.br/api/compress
Authorization: Bearer pf_SEU_TOKEN
Content-Type: application/json

{
  "text": "{{texto_do_zap}}",
  "compression_level": "high"
}

GET https://prosefold.narra.com.br/api/documents/123/content?type=prosefold
Authorization: Bearer pf_SEU_TOKEN

1. GET /api/documents
2. GET /api/documents/{id}/content?type=prosefold
3. POST /api/compress

Agentes de código e CLIs

Qualquer agente que consiga fazer chamadas HTTP pode usar o ProseFold pela API. Skills, plugins e MCP não são obrigatórios; eles só tornam o uso mais natural, para que o agente descubra ferramentas sem você colar endpoints a cada conversa.

Recomendação prática: mantenha uma integração REST simples para Python/Node.js, crie um servidor MCP ProseFold para clientes compatíveis e só crie Skills/Plugins quando quiser empacotar comportamento para um agente específico.

Tamanho do documento

O limite principal é medido em tokens de entrada, depois da conversão para Markdown. URLs públicas, inclusive PDFs públicos, são enviadas por JSON com o campo url. Upload de arquivo local usa multipart e aceita até 64 MB por requisição no VPS; PDFs precisam ter texto selecionável. A leitura de conteúdo por JSON recusa arquivos acima de 12 MB; nesse caso, leia uma variante ProseFolded/minificada ou use a biblioteca web.

Referência: o documento de exemplo da capa tem 75.932 tokens / 1.468 KB no original e 7.895 tokens / 32 KB no ProseFolded. O ProseFolded pode ser lido em uma chamada com page_size_chars=60000, ou paginado se o agente usar o padrão.

Texto ou Markdown em JSON

Use quando seu sistema já tem texto, Markdown, transcript ou conteúdo extraído.

curl -X POST https://prosefold.narra.com.br/api/compress \
  -H "Authorization: Bearer pf_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "## Documento\nTexto longo...",
    "compression_level": "high"
  }'

URL ou YouTube

Use quando o agente tiver um link em vez de um arquivo. O ProseFold busca a página, PDF público ou transcript do YouTube no servidor, converte para Markdown e enfileira a compressão.

curl -X POST https://prosefold.narra.com.br/api/compress \
  -H "Authorization: Bearer pf_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=...",
    "compression_level": "high",
    "transcriptapi_key_source": "system"
  }'

Para páginas e PDFs públicos, use o mesmo campo url. Para YouTube, o topo do Markdown inclui título, descrição e link do vídeo quando disponíveis.

Arquivo

Use multipart apenas quando o arquivo está localmente no seu sistema e precisa ser enviado inteiro ao ProseFold. Formatos aceitos: TXT, MD, HTML, DOCX, XLSX e PDF com texto selecionável. Para um PDF público na web, prefira JSON com url; o servidor baixa, converte e enfileira o documento.

curl -X POST https://prosefold.narra.com.br/api/compress \
  -H "Authorization: Bearer pf_SEU_TOKEN" \
  -F "document=@/caminho/documento.pdf" \
  -F "compression_level=ultra"

JavaScript: enfileirar compressão

const response = await fetch("https://prosefold.narra.com.br/api/compress", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pf_SEU_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: mensagemLonga,
    compression_level: "high"
  })
});

const result = await response.json();
const jobId = result.job_id;

PHP

$payload = json_encode([
    "text" => $texto,
    "compression_level" => "high",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://prosefold.narra.com.br/api/compress");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer pf_SEU_TOKEN",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => $payload,
]);

$result = json_decode(curl_exec($ch), true);
$jobId = $result["job_id"] ?? null;

Integrações típicas

Em um chatbot, envie documentos, páginas ou transcripts ao ProseFold antes de montar o contexto do modelo. Em GPT Actions, liste a biblioteca e leia o ProseFolded sob demanda, sem copiar documentos manualmente para dentro do GPT.