Var specifikationen finns
Endpoint-specifikationen genereras live från API-katalogen. Använd dessa filer istället för att kopiera endpoint-listor från artiklar:
- Kompakt index för AI-klienter:
https://api.paperoffice.ai/latest/docs/llms.txt - Fullständig referens:
https://api.paperoffice.ai/latest/docs/llms-full.txt - OpenAPI 3.1:
https://api.paperoffice.ai/latest/docs/openapi.json - Agentfärdighet:
https://api.paperoffice.ai/latest/docs/skill.md - Postman-samling:
https://api.paperoffice.ai/latest/docs/postman
Dokumentationsruterna är offentliga och kräver ingen token. Importera Postman-URL:en i Postman, VS Code eller Bruno, och ladda ner den igen när dokumentationsutgåvan ändras. Produktionsbasadressen är https://api.paperoffice.ai/latest; använd /dev endast för utveckling.
En snabbstart med en AI-kodningsassistent: ge den adressen till llms-full.txt och beskriv den funktion du behöver, till exempel en funktion som skickar en bild och returnerar den igenkända texten.
Autentisering och token-typer
De flesta produktendpoints kräver en bearer-token i Authorization-huvudet. Du skapar token i PaperOffice-appen under Konto → API.
- Systemnyckel (po_sk_): server-till-server-integration med fullt API-åtkomst. Använd den aldrig i en webbläsare.
- Användartoken (po_ut_): omfattar en användare, till exempel för MCP. Rättigheter följer användaren och licensen.
- Grupp-token (po_gt_): ärver rättigheterna och arbetsytans vitlista från en användargrupp.
- Publicerbar nyckel (po_pk_): för användning i en webbläsare. Varje begäran kräver en ursprungskälla som nyckelägaren har angett, en samlad budget begränsar förbrukningen, och radering, kontohantering, nyckelhantering och betalningsändringar förblir blockerade. Den är inte tillåten för MCP.
Utan token är endast infrastrukturendpoints såsom specifikationen, hälsokontrollen och anslutningstestet tillgängliga. En produktbegäran utan token besvaras med HTTP 403 och koden TIER_RESTRICTED, inte med HTTP 401.
Jobb: väntning, polling och resultat
Bearbetning körs som jobb. Jobbsökvägar använder mönstret handler___command med tre understreck, till exempel POST /job/add/paperoffice_aiocr___generate för textigenkänning. Punktnotation avvisas med JOB_CONFIG_INVALID.
- Som standard håller begäran anslutningen öppen en stund. Om jobbet avslutas i tid får du resultatet direkt. Annars får du HTTP 202 med ett jobbid och en poll-adress, och jobbet fortsätter att köras.
- HTTP 202 är en framgång, inte ett fel. Polla
GET /job/get/{job_id}var 5:e till 10:e sekund tills statusen är completed. Resultatet finns då i job_result. - Med client_wait=false får du jobbidet omedelbart och börjar polla från start.
- Alla svar är JSON. Klienter bör läsa det stabila code-fältet, inte den lokaliserade meddelandetexten.
Du ser köade, körande och avslutade API-jobb i appen under Konto → API → Jobbkö. Den fullständiga listan över felkoder finns i specifikationen; vanliga fall är saknade eller ogiltiga parametrar (400), en saknad eller ogiltig token (401), otillräckliga Credits (402), en förbjuden åtgärd (403) och för många begäranden (429, respektera Retry-After).
Start SLA: när ett jobb startar
Det valfria fältet processing_lane styr när ett jobb startar i kön, inte när det avslutas. client_wait styr om anslutningen väntar på resultatet; de två fälten är oberoende av varandra.
Utan processing_lane gäller arbetsytans standardinställning, annars gäller best effort. Varje plan inkluderar best effort utan tilläggsavgift. Snabbare startkanaler är valfria och kostar mer. De aktuella kanalerna och deras priser finns tillgängliga i realtid via API-prislistan; detaljer finns i API-dokumentationen.
Webhooks
Webhook-slutpunkter tar emot händelser för jobb och konton, till exempel job.completed, job.failed, job.progress samt händelser för dokument, arbetsytor och uppgifter. Kontomeddelanden såsom en tom plånbok eller en återkallad nyckel är inte webhook-händelser.
- Payloaden signeras med HMAC-SHA256 i rubriken X-Paperoffice-Signature. Beräkna signaturen över den råa begärans kropp med din webhook-hemlighet och avvisa begäran om den inte stämmer överens.
- Webhooks registreras, listas, uppdateras, testas och tas bort via API:et.
Fakturering och användning
API-anrop förbrukar Credits från organisationens delade pool, samma pool som appen. Vissa status- och hälsoförfrågningar debiteras inte; detaljer finns i API-dokumentationen. Anrop som avvisas på grund av ogiltig inmatning debiteras också; anrop som begränsas av hastighetsgränsen debiteras inte.
Du ser anropen med deras Credits under API & Utvecklare → API-användning: liveloggen visar varje förfrågan, historiken visar användningen per datum, hanterare och åtgärd. När Credits tar slut avvisas anrop tills saldot fylls på eller automatisk påfyllning träder i kraft. Hastighetsgränserna beror på din plan; aktuella gränser och svarshuvuden beskrivs i API-dokumentationen. Mer om Credits: Fakturering och Credits i PaperOffice AI.
MCP: anslut AI-assistenter
MCP kopplar AI-assistenter som Claude, ChatGPT, Grok och Cursor direkt till PaperOffice. Autentisering sker via OAuth 2.1 eller en användar- eller grupp-token; systemnycklar och publicerbara nycklar är blockerade för MCP. Produktionsvärd är https://mcp.paperoffice.ai, med profiler som /claude, /chatgpt, /grok, /cursor och /dms. Installation, behörigheter och dataflöde: Använda PaperOffice med Claude, ChatGPT, Grok och Cursor.
Vanliga frågor
- Var hittar jag alla slutpunkter? I llms.txt, llms-full.txt och OpenAPI-filen. De genereras i realtid.
- Vilken token ska min server använda? En systemnyckel, aldrig i en webbläsare. För en webbläsare används en publicerbar nyckel med ursprung och budget.
- Är HTTP 202 ett fel? Nej. Jobbet körs fortfarande; polla för resultatet.
- Kostar snabbare startköer mer? Ja. Best effort har ingen tilläggsavgift; aktuella priser finns i API-prislistan.
- Debiteras avvisade anrop? Anrop som avvisas på grund av ogiltig inmatning debiteras; anrop som begränsas av hastighetsgränsen debiteras inte.