Bestanden en artefacten via de API¶

Op deze pagina upload je bestanden om ze in modelverzoeken te gebruiken, en download je artefacten: de bestanden die tools hebben gemaakt. Je sleutel heeft voor uploads de capability files nodig, en voor artefacten zowel artifacts als files. Dezelfde bestanden beheer je met de muis in Bestanden in de console. Een opgeslagen HTML-bestand kun je ook in een browser tonen, met een link delen en onder een naam als pagina publiceren (Pagina's).

Core bewaart uploads en toolbestanden in een eigen collectie per API-sleutel. Die collectie wordt bij de eerste opslag automatisch aangemaakt en krijgt het id van de sleutel als naam. De sleutel heeft toegang tot deze collectie, ook als het beleid andere collectienamen beperkt. Bestandsbeleid en eventuele controles per persoon blijven van toepassing.

Een bestand uploaden¶

curl -s -X POST "$CORE_URL/files" \
    -H "Authorization: Bearer $CORE_KEY" \
    -F "file=@factuur.pdf" \
    -F "purpose=attachment"

Drie optionele velden staan ernaast:

• collection_id -- zet het bestand in een eigen kenniscollectie in plaats van die van je sleutel. De collectie moet er een zijn die je sleutel bereikt. In de eigen collectie van een sleutel en in de collectie uploads van je organisatie is de upload een bestand: je sleutel heeft files nodig, en de naam wordt tegen haar bestandsbeleid gehouden. In elke andere collectie is de upload een kennisdocument: je sleutel heeft de capability knowledge nodig, anders geeft de upload 403, en de naam wordt niet tegen het bestandsbeleid gehouden. Een bestand dat een persoon via de beheerroute POST /tenants/{id}/files uploadt, komt in de collectie uploads van die organisatie als er geen wordt genoemd: een beheerder heeft geen sleutel en dus geen eigen collectie.
• retention -- window of keep. window betekent dat het bewaarvenster van je organisatie het bestand omvat: het wordt verwijderd zodra het ouder is dan het venster dat je beheerder heeft ingesteld (en nooit, als er geen is ingesteld). keep betekent dat het blijft tot iets het verwijdert. De eigen collectie van je sleutel staat standaard op window, een collectie die je zelf maakt op keep.
• folder -- zet het bestand in een map van zijn collectie, een pad als contracten/2026. Core maakt het pad netjes zoals bij een bestand verplaatsen; leeg of weggelaten is de hoofdmap van de collectie.

Een geslaagde upload geeft 201, een Location-header en bestandsmetadata terug:

{
  "id": "src_3Wq8...",
  "object": "file",
  "kind": "file",
  "filename": "factuur.pdf",
  "purpose": "attachment",
  "media_type": "application/pdf",
  "bytes": 48211,
  "sha256": "9f2c...",
  "collection_id": "col_5Km2...",
  "folder": null,
  "retention": "window",
  "index_status": "ready"
}

folder zegt waar het bestand staat, met het pad zoals Core het netjes maakte, en is null in de hoofdmap van de collectie; GET /files neemt folder om één map op te vragen. Vergelijk sha256 met de hash van je lokale bestand om de upload te controleren.

Een bestandsnaam met een stuurteken geeft 422 op file, en er wordt niets opgeslagen.

Behandel de id als ondoorzichtig: een nieuwe upload krijgt een src_...-id, en een bestand dat je voor 17-09-2026 uploadde houdt het file_...-id dat het toen kreeg. Beide noemen hetzelfde en werken op elke aanroep hieronder.

Je bestanden zijn doorzoekbaar¶

Een upload in de eigen collectie van je sleutel wordt geïndexeerd, en de upload wacht daarop, zodat je volgende beurt het zojuist verstuurde bestand kan doorzoeken. index_status in het antwoord zegt hoe ver dat kwam:

De upload wacht tot 30 seconden tot het indexeren klaar is. Dat getal is van je installatie (CORE_FILES_INGEST_WAIT_SECONDS); vraag je operator als je een andere waarde moet weten. Een installatie die op 0 staat wacht nooit, en elke upload antwoordt dan queued. Een bestand dat langer duurt antwoordt processing: het indexeren stopt als de wachttijd om is, en het bestand kan ongeveer vijf minuten processing blijven voordat het indexeren opnieuw vanaf het begin start. Er gaat niets verloren, en je hoeft het bestand niet opnieuw te uploaden.

index_error_code zegt waarom een bestand dat failed is niet geïndexeerd werd, als één code uit een vaste reeks (Waarom indexeren mislukte), en is null bij elke andere status.

Een bestand dat queued is en waarvan het antwoord ook parked_until bevat, wordt vastgehouden: je sleutel of je organisatie heeft de maandelijkse kostenlimiet bereikt, en indexeren zou geld kosten aan embeddings of aan een modelstap van de pipeline van de index. Het wordt geïndexeerd op dat moment, het begin van de volgende maand (UTC), of eerder zodra de limiet wordt verhoogd of opgeheven; opnieuw uploaden hoeft niet. parked_until is null zolang niets het bestand tegenhoudt.

Doorzoeken vraagt geen eigen tool: elke beurt van je sleutel krijgt knowledge__uploads aangeboden, een zoekopdracht over die ene collectie -- wat je uploadde en wat je tools maakten. Je beheerder kan het indexeren per sleutel uitzetten, in de files-configuratie van die sleutel (index_uploads) op POST /tenants/{id}/keys of PATCH /tenants/{id}/keys/{key_id} -- de console heeft er vandaag geen veld voor, dus het is een API-aanroep -- en een beleid dat knowledge__uploads weigert haalt de tool weg; een sleutel zonder knowledge houdt haar bestanden en indexeert er geen. Op een bestand dat een persoon via de beheerroute uploadt wordt niet gewacht: dat komt in de wachtrij zoals elke andere kennisbron.

Wie een upload vindt. Noemen je verzoeken de persoon voor wie ze zijn, dan beslissen de regels van de soort stored_file over uploads en artefacten, waar ze ook worden bereikt: op GET /files, tussen de bronnen van een collectie, en in wat knowledge__uploads vindt. Onder de standaardregels vindt een persoon haar eigen uploads en de gedeelde, geüpload door een verzoek dat niemand noemde, en nooit die van een ander. Andere soorten kennisbronnen volgen de regels van de soort knowledge_source (Bouwen voor personen).

Wat indexeren uit een bestand leest¶

De eigen index van je sleutel heeft geen eigen pipeline, dus elk bestand krijgt de standaard voor zijn soort: van een spreadsheet, een CSV of een JSON-bestand worden de tabellen uitgelezen, en van elk ander document wordt de tekst opgeknipt en ge-embed. Je sleutel kan voor die index een andere pipeline kiezen (Sjablonen).

Een PDF wordt gelezen uit zijn tekstlaag, de tekst die een PDF bij zich draagt om te selecteren en te kopiëren. Of een PDF tekst heeft, wordt beoordeeld voor het document als geheel, niet per pagina. Een PDF met een paar gescande pagina's wordt geïndexeerd uit de pagina's met tekst, voegt niets toe voor de gescande pagina's, en is ready. Alleen een PDF waarin geen enkele pagina tekst heeft mislukt, met needs_ocr. Om gescande pagina's te indexeren heeft de index een pipeline met een parseerdienst nodig (ingest/llama-parse), waar je installatie er een heeft.

Het model ziet nooit een afbeelding in een PDF of een Word-bestand. De standaardpipeline leest alleen tekst. Met de pipeline ingest/with-images worden de afbeeldingen ge-embed zodat een tekstvraag ze vindt (Afbeeldingen gevonden met woorden), maar een zoekopdracht geeft het model een regel die de afbeelding noemt, [image <media type>: <path>], niet de afbeelding zelf. Ook builtin__read_document geeft alleen tekst (Een heel document lezen).

Waarom indexeren mislukte¶

Een bestand dat failed is draagt een van deze codes in index_error_code; een document in een kennisindex draagt dezelfde code als error_code in GET /knowledge/indexes/{id}/sources. Het bestand zelf blijft opgeslagen en downloadbaar, welke code het ook heeft.

De standaardpipelines, die de eigen index van je sleutel gebruikt, kunnen met deze codes mislukken:

Een pipeline die jij of je beheerder bouwde kan ook met deze codes mislukken:

Groottelimieten¶

Uploads boven de groottelimiet geven 413. Core kan ze al vóór het lezen van de inhoud weigeren als Content-Length te groot is. De installatie bepaalt het maximum; de configuratie files van je sleutel kan dit verlagen. Bekijk de sleutelinstelling met GET /key. Een upload zonder geldige sleutel krijgt 401 voordat Core hem leest. Een upload moet binnen 300 seconden aankomen, anders antwoordt de gateway 408; bij de standaardgrens van 25 MiB vraagt dat een uploadsnelheid van ongeveer 0,7 Mbit/s (Tijdslimiet voor een verzoek).

Een groot bestand in delen uploaden¶

Een bestand dat groter is dan één upload mag zijn, of dat een weggevallen verbinding moet overleven, gaat naar binnen via een uploadsessie: je meldt het bestand aan, stuurt het in genummerde delen en rondt de sessie af. Delen mogen in elke volgorde en meerdere tegelijk komen, en een deel dat mislukte stuur je gewoon opnieuw. Uploaden in delen vraagt een organisatie waarvan de bestanden in een object store staan; bij een organisatie die ze in haar database bewaart krijgt de sessie 409 en is POST /files de weg naar binnen.

Open de sessie met de naam, het type en de exacte grootte van het bestand:

curl -s -X POST "$CORE_URL/uploads" \
    -H "Authorization: Bearer $CORE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"filename": "site-survey.mp4", "media_type": "video/mp4",
         "size_bytes": 734003200, "target": {"kind": "file", "purpose": "survey"}}'

Het antwoord bevat de id van de sessie, haar part_size_bytes (8 MiB, tenzij je installatie anders instelt) en haar part_count. target neemt de velden die POST /files neemt: purpose, en optioneel folder, collection_id, labels en retention. Met een optionele sha256 van het hele bestand controleert Core de opgeslagen bytes daartegen.

Knip het bestand in delen van precies part_size_bytes, het laatste deel de rest, en stuur elk deel als de kale inhoud van het verzoek:

split -b 8388608 -d -a 4 site-survey.mp4 part-
curl -s -X PUT "$CORE_URL/uploads/$SESSION/parts/1" \
    -H "Authorization: Bearer $CORE_KEY" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @part-0000

Elk deel antwoordt met zijn sha256 zoals Core het ontving. Een deel dat langer is dan zijn grootte geeft 413, een korter 422, en 503 met Retry-After betekent dat Core zoveel delen tegelijk ontvangt als het mag: wacht dat aantal seconden en stuur het opnieuw. Na een weggevallen verbinding toont GET /uploads/$SESSION welke delen aankwamen; stuur de rest.

Zijn alle delen binnen, rond de sessie dan af en vraag haar op:

curl -s -X POST "$CORE_URL/uploads/$SESSION/complete" -H "Authorization: Bearer $CORE_KEY"
curl -s "$CORE_URL/uploads/$SESSION" -H "Authorization: Bearer $CORE_KEY"

Afronden antwoordt 202; de sessie is completing terwijl Core het bestand samenstelt en controleert, daarna completed, met de file_id die je als elk ander bestand gebruikt. Een sessie die failed is, zegt waarom in error_code. DELETE /uploads/$SESSION laat een open sessie en haar delen vallen. Een sessie blijft standaard 24 uur open (expires_at); daarna vallen haar delen weg. Een afgelopen sessie is daarna nog even lang op te vragen, zodat een late vraag haar file_id niet mist.

De groottelimiet van een sessie is het plafond van je installatie (standaard 5 GiB), verlaagd door de eigen files-limiet van je sleutel. Een bestand boven de gewone uploadlimiet wordt opgeslagen, is te downloaden en te exporteren, maar wordt niet doorzoekbaar gemaakt.

Opgeslagen bestanden opvragen, downloaden en wijzigen¶

Bestanden opvragen¶

Zonder filter geeft GET /files de uploads in de eigen collectie van je sleutel. Deze queryparameters veranderen wat de lijst bevat:

• kind -- welke soorten bestanden je wilt zien. Herhaal de parameter om er meerdere te noemen: file (een upload), artifact (een bestand dat een tool maakte), en text, records en connector (kennisdocumenten). Core geeft alleen de soorten die je noemt. Een soort waarvoor je sleutel de capability mist, ontbreekt in de lijst; de aanroep zelf slaagt gewoon.
• collection_id -- vraag één andere collectie op die je sleutel bereikt, in plaats van haar eigen collectie. Een collectie die je sleutel niet bereikt, geeft 404.
• trashed -- true geeft in plaats daarvan de bestanden in de prullenbak, met dezelfde filters.

# je uploads en de bestanden die je tools maakten
curl -s "$CORE_URL/files?kind=file&kind=artifact" \
    -H "Authorization: Bearer $CORE_KEY"

# elk document in één kenniscollectie
curl -s "$CORE_URL/files?collection_id=col_2Pf7...&kind=file&kind=text&kind=records&kind=connector" \
    -H "Authorization: Bearer $CORE_KEY"

Elke rij zegt in kind wat ze is. Een rij van de soort artifact noemt ook de response_id, call_id en tool_name waaruit ze is ontstaan.

Wat een bestands-id bereikt¶

/files/{file_id} accepteert het id van elk opgeslagen bestand, niet alleen dat van een upload. Hetzelfde id werkt op /artifacts/{artifact_id} als het bestand een artefact is, en op /knowledge/collections/{collection_id}/sources/{source_id} voor alles in die collectie. Welke capability je sleutel nodig heeft, hangt af van wat het bestand is, niet van de route die je aanroept:

De /files-routes zelf vereisen files: een sleutel met knowledge maar zonder files leest haar documenten via de bronroutes van de collectie. Die routes passen dezelfde tabel toe: een sleutel zonder artifacts vindt geen artefact tussen de bronnen van een collectie, en een sleutel zonder files vindt er geen upload.

Lezen op id is niet beperkt tot de bestanden die je eigen sleutel opsloeg. Elke sleutel van je organisatie leest een bestand op zijn id als drie controles het alle drie toestaan:

1. De collectie. Je sleutel bereikt altijd haar eigen collectie. Elke andere collectie -- de eigen collectie van een andere sleutel, de collectie uploads van je organisatie, een kenniscollectie -- bereikt ze als de regels van je sleutel over knowledge_collection de naam van die collectie toestaan. De eigen collectie van een sleutel heet naar het id van die sleutel (key_...).
2. De capability en de bestandsnaam, zoals de tabel hierboven zegt.
3. De persoon. De regels over stored_file (uploads en artefacten) of knowledge_source (alle andere documenten) beslissen voor de persoon die het verzoek noemt in X-Core-Subject of via zijn subject-token. Onder de standaardregels leest een verzoek voor Anna haar eigen uploads en artefacten en de gedeelde, opgeslagen door een verzoek dat niemand noemde, en nooit die van een ander. Elk ander document bereikt iedereen, tot een regel over knowledge_source het beperkt. Een verzoek dat niemand noemt, leest elk bestand dat de eerste twee controles toestaan.

Welke sleutel het bestand uploadde, is geen van de controles. Onder de standaardregels bereikt elke sleutel elke collectie, dus een tweede sleutel van je organisatie kan een upload van de eerste op id lezen.

Een bestand dat deze controles weigeren, geeft 404, hetzelfde antwoord als een id dat niet bestaat, bij metadata, inhoud, wijzigen en verwijderen, en een lijst laat het weg. Een subject-token wordt op dezelfde manier beoordeeld, onder de regels van de sleutel waarmee het is gemaakt: een bestand in een collectie die die regels niet bereiken, geeft 404, ook als het bestand van de eigen persoon van het token is.

Wil je een sleutel buiten de collecties van andere sleutels houden, geef haar dan een regel over knowledge_collection die alleen de collecties noemt die ze moet bereiken, in plaats van de standaardregel met het id knowledge-collection. Haar eigen collectie blijft bereikbaar, wat de regel ook zegt:

{"id": "shared-collections", "effect": "permit", "kind": "knowledge_collection",
 "match": {"names": ["uploads", "handbook-*"]}}

Hoe je de regels van een sleutel wijzigt, staat in Je eerste regel schrijven.

Een bestand downloaden¶

curl -s "$CORE_URL/files/src_3Wq8.../content" \
    -H "Authorization: Bearer $CORE_KEY" -o factuur.pdf

Het antwoord bevat de opgeslagen bytes als bijlage, met Content-Length en de huidige bestandsnaam in Content-Disposition. De naam is procentgecodeerd (attachment; filename*=UTF-8''factuur.pdf), dus decodeer hem voordat je hem als lokale naam gebruikt.

Een kennisdocument download je op dezelfde manier, hier of met GET /knowledge/collections/{collection_id}/sources/{source_id}/content: een geüpload document komt terug als het bestand dat is geüpload, een text-bron als haar tekst, en een records-bron als een JSON-array van haar records. De bytes van een artefact vragen op elke route een regel die artefacten downloaden toestaat (Downloadfouten).

Een bestand hernoemen, verplaatsen of bewaren¶

curl -s -X PATCH "$CORE_URL/files/src_3Wq8..." \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"filename": "factuur-2026-041.pdf", "retention": "keep"}'

Stuur een of meer van filename, retention, folder en collection_id; een veld dat je weglaat, houdt zijn waarde. Het antwoord is de metadata van het bestand, met updated_at op het moment van de wijziging. De inhoud en de soort van een bestand liggen vast.

• filename -- 1 tot 255 tekens. Van een bestand of een artefact -- soort file of artifact, ook een bestand dat rechtstreeks in een kenniscollectie is geüpload -- bewaart Core het laatste deel van het pad, dus rapporten/q3.pdf wordt opgeslagen als q3.pdf, en blijft er niets over, dan geeft de aanroep 422 op filename. Een bron van de soort text, records of connector heeft een titel en geen bestandsnaam, en die wordt opgeslagen zoals je hem schreef. Een naam met een stuurteken geeft voor elke soort 422 op filename. De nieuwe naam van een upload moet er een zijn die het bestandsbeleid van je sleutel noemt; anders geeft het hernoemen 403 en houdt het bestand zijn naam.
• retention -- window zet het bestand onder het bewaarvenster van je organisatie, keep bewaart het tot iets het verwijdert.
• folder -- de map waar het bestand heen gaat, een pad als contracten/2026. Core maakt het pad netjes, dus /contracten//2026/ is dezelfde map, en geeft 422 op folder voor een deel . of .., een stuurteken, of een pad dat na het netjes maken langer is dan 512 tekens. Een lege folder zet het bestand in de hoofdmap van de collectie. Een document dat een connector synchroniseert, houdt de map die de bron het geeft: zo'n document verplaatsen geeft 409, dus verplaats het in de bron.
• collection_id -- de collectie waar het bestand heen gaat. Een upload of een artefact gaat alleen tussen de eigen collectie van je sleutel en de collectie uploads van je organisatie, en alleen naar een collectie die je sleutel bereikt; al het andere geeft 422 op collection_id. Een bestand dat uit de eigen collectie van je sleutel gaat, wordt niet meer doorzocht door de beurten van je sleutel. Wil je een bestand in een kenniscollectie, kopieer het daarheen.

Een map hernoemen of verplaatsen¶

curl -s -X POST "$CORE_URL/files/folders/move" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"collection_id": "col_2Pf7...", "from": "inbox", "to": "archief/2026"}'

Elk bestand dat je sleutel bereikt in from, en in de mappen daaronder, gaat naar dezelfde plek onder to: inbox/laat wordt archief/2026/laat. Het antwoord noemt de twee mappen zoals Core ze netjes maakte, en hoeveel bestanden zijn verplaatst (moved). Het is alles of niets: mag je sleutel een van de bestanden niet wijzigen, dan gaat er niets, en het antwoord is het antwoord dat dat ene bestand zou geven, met zijn id. Een bestand dat je sleutel niet ziet, blijft waar het is. Een to gelijk aan of binnen from geeft 422 op to, een lege from geeft 422 op from; een collectie die je sleutel niet bereikt, geeft 404; en een map van meer dan 500 bestanden geeft 422 op from; verplaats dan eerst de mappen daaronder.

Een bestand verwijderen, terugzetten of definitief weggooien¶

DELETE /files/{file_id} legt een bestand van elke soort die je sleutel bereikt in de prullenbak. Vanaf dat moment is het weg uit elke lezing: het staat in geen lijst, zijn id geeft 404, een zoekopdracht vindt het niet meer, en een link of weergaveadres ernaar opent niet meer. Zijn bytes blijven bewaard, en tellen nog mee in wat je organisatie opslaat, tot de prullenbak wordt geleegd: 30 dagen later, tenzij je operator een ander aantal instelde.

# de prullenbak opvragen: elk bestand zegt wanneer het is verwijderd en wanneer het definitief weggaat
curl -s "$CORE_URL/files?trashed=true" -H "Authorization: Bearer $CORE_KEY"

# er een terugzetten
curl -s -X POST "$CORE_URL/files/src_7Hq2.../restore" -H "Authorization: Bearer $CORE_KEY"

Een bestand in de prullenbak draagt deleted_at en purge_at, die null zijn voor een bestand dat er niet in ligt. De geïndexeerde tekst verdwijnt uit elke index en kennisgraaf in hetzelfde verzoek dat het bestand naar de prullenbak verplaatst. POST /files/{file_id}/restore zet het terug waar het stond, in zijn collectie en map, en geeft zijn metadata; elke index die het bestand opneemt, indexeert het opnieuw vanaf het begin, dus het is weer doorzoekbaar zodra zijn index_status ready zegt. Opnieuw indexeren kost niets in een index die sinds de eerste keer niet opnieuw is geïndexeerd, omdat dat verbruik al geteld is; een index die intussen opnieuw is geïndexeerd, en elke kennisgraaf die het bestand opneemt, tellen het opnieuw. Terugzetten is een wijziging van het bestand, dus je sleutel heeft nodig wat een hernoeming nodig heeft, en een bestand dat niet in de prullenbak ligt, geeft 404. DELETE op een bestand dat al in de prullenbak ligt, verwijdert het met zijn bytes meteen; daarna kun je het niet meer terugzetten. Een client die een verwijdering herhaalt, haalt het bestand dus definitief weg: lees het bestand vóór je het opnieuw probeert met GET /files/{file_id}, en probeer alleen opnieuw bij een 200; een 404 betekent dat het al in de prullenbak ligt of weg is.

Een bestand dat een pagina toont, kun je niet verwijderen zolang die het toont (Een gepubliceerd bestand blijft bewaard). Drie verwijderingen slaan de prullenbak over: de synchronisatie van een connector die een document weghaalt dat zijn bron weghaalde, het bewaarvenster van je organisatie, en het wissen van de gegevens van een persoon. Een collectie verwijderen haalt ook haar bestanden definitief weg, ook die in de prullenbak.

Een subject-token hernoemt, verplaatst, verwijdert en zet alleen de uploads en artefacten van zijn eigen persoon terug. Voor een gedeeld bestand, en voor elk kennisdocument, geeft de aanroep 403; doe hem vanuit je backend met je sleutel.

Bestanden en afbeeldingen meesturen¶

Gebruik input_file om een bestandsverwijzing mee te sturen in een gebruikersbericht. Dit geeft alleen metadata door: het model kan de pdf in dit voorbeeld niet lezen. Geef uitgelezen tekst mee of indexeer het document om vragen over de inhoud te stellen.

{
  "model": "<een model-id>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Wat is het totaalbedrag op deze factuur?" },
        { "type": "input_file", "file_id": "src_3Wq8..." }
      ]
    }
  ]
}

Bestands- en afbeeldingsbijlagen worden verschillend verwerkt:

• Bestandsverwijzingen: input_file stuurt een melding met het bestands-id en mediatype. Het document wordt niet uitgelezen of verwerkt.
• Afbeeldingen: synchrone aanroepen ondersteunen input_image met een geüploade afbeelding of een inline data:image/...-URL. PNG, JPEG, GIF en WebP zijn toegestaan, tot 5 MiB per afbeelding. Core haalt geen afbeelding op van een webadres. Een optionele detail (auto, low of high) zegt hoe nauwkeurig het model moet kijken; het gaat mee naar een model uit de OpenAI-familie en wordt voor elk ander model weggelaten. Achtergrondtaken kunnen momenteel geen van beide vormen laden.
• Opnames: input_audio draagt een opname mee, inline of met file_id. Core transcribeert haar voordat het model wordt aangeroepen, en het model leest de tekst; zie Audio transcriberen.
• Afbeeldingen in een toolresultaat: de output van een function_call_output mag een lijst van input_text- en input_image-delen zijn in plaats van een string, als een tool die je zelf uitvoerde met een afbeelding antwoordt. Dezelfde limieten gelden, en het model leest de afbeelding als deel van het resultaat van die tool. In een achtergrondtaak leest het in plaats daarvan [image unavailable].

Een niet-beschikbaar bestands-id geeft 404, ook wanneer het beleid van je sleutel dat bestand niet noemt. Bij het voortzetten van een gesprek laadt Core afbeeldingen opnieuw die eerdere beurten met een file_id meestuurden. Een inline data:-afbeelding wordt niet bewaard, dus een latere beurt leest op die plek [image unavailable]; upload de afbeelding en stuur haar file_id mee als latere beurten haar opnieuw moeten zien. Is een geüploade afbeelding verwijderd of ligt ze in de prullenbak, of noemt het beleid van je sleutel het bestand inmiddels niet meer, dan ontvangt het model ook [image unavailable] en gaat de beurt door.

Het beleid van je sleutel werkt op de opgeslagen bestandsnaam: bestanden die het niet noemt, staan niet in GET /files en geven 404 op hun id. Een upload waarvan de bestandsnaam buiten het beleid valt, geeft 403 voordat er iets is opgeslagen. Dat geldt voor elke upload die een bestand wordt, via POST /files en evengoed via de uploadroute van een collectie naar de eigen collectie van je sleutel; voor een kennisdocument bestaat die controle niet.

input_file accepteert ook het id van een artefact: een bestand dat een tool maakte, is een bestand als elk ander. Dat geldt ook voor kind: "file" als je een bron aan een kenniscollectie toevoegt -- maar een artefact kopiëren is het downloaden ervan, dus het wordt geweigerd met 403 als geen regel je sleutel toestaat artefacten te downloaden.

Artefacten¶

Als een tool binaire uitvoer maakt, zoals een grafiek of document, slaat Core die op als artefact. Het toolresultaat bevat een verwijzing die het model ontvangt. Uitvoer boven 25 MiB wordt weggelaten en vervangen door [binary output omitted: <n> bytes], waarbij <n> de grootte van de uitvoer is. Het antwoord van een HTTP-tool wordt niet verder gelezen dan 25 MiB (10 MiB voor JSON en tekst); daarboven krijgt het model [binary output omitted: more than <n> bytes], waarbij <n> die grens in bytes is.

Artefacten ontstaan bij de uitvoering van tools. Je kunt ze niet direct via de API uploaden. Een artefact komt in dezelfde collectie als je uploads en heeft geen eigen vervaltermijn: het blijft precies zo lang als elk ander bestand daar -- onder het bewaarvenster van je organisatie, tenzij je zijn retention op keep zet.

Elk artefact draagt response_id, call_id en tool_name: het antwoord, de toolaanroep en de tool waaruit het is ontstaan. Het heeft ook een filename: de naam die de tool het bestand gaf, of <tool>-<call_id> plus de extensie van het mediatype (.png bij een afbeelding) als de tool er geen gaf, en een folder, null in de hoofdmap van de collectie. Een download krijgt de bestandsnaam, en je kunt hem wijzigen:

curl -s -X PATCH "$CORE_URL/artifacts/art_8Lp4..." \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"filename": "omzet-q3.png", "retention": "keep"}'

Voor de body gelden dezelfde regels als voor PATCH /files/{file_id}, behalve dat de naam van een artefact niet tegen het bestandsbeleid van je sleutel wordt gehouden.

Een artefact is ook een opgeslagen bestand. GET /files?kind=artifact geeft de artefacten in de collectie van je sleutel, en /files/{file_id} leest, downloadt, hernoemt, verwijdert en zet er een terug met hetzelfde id (Wat een bestands-id bereikt). Een verwijderd artefact gaat naar de prullenbak zoals een bestand (Een bestand verwijderen, terugzetten of definitief weggooien).

Downloadfouten¶

• 403: geen regel staat je sleutel toe artefacten te downloaden, of een regel verbiedt het. Dat geldt op elke route die de bytes van een artefact uitgeeft: GET /artifacts/{artifact_id}/content, GET /files/{file_id}/content en GET .../sources/{source_id}/content van een collectie. Vraag je beheerder om een regel die artefacten downloaden toestaat, of om de regel die het verbiedt weg te halen.
• 404: het artefact is niet beschikbaar, hoort bij een andere organisatie, ligt in de prullenbak, of is al verwijderd -- door jou, of doordat het bewaarvenster van je organisatie over de collectie van je sleutel sloot. Markeer wat je wilt houden met PATCH /artifacts/{artifact_id} en {"retention": "keep"}.

Pagina's¶

Een opgeslagen HTML-bestand kun je in een browser tonen in plaats van het te downloaden. Een HTML-bestand is hier een upload of een artefact waarvan media_type text/html is. Een kennisdocument kun je zo niet tonen, ook niet als het HTML is, en een SVG- of XHTML-bestand evenmin.

Je toont een HTML-bestand op zijn eigen id, of je publiceert het als pagina: een eigen naam boven de versies van een rapport, met adressen die blijven werken als je een nieuwe versie publiceert (Een pagina publiceren onder een naam). Een pagina heeft een eigen id, pg_..., naast de ids van haar bestanden.

Er zijn twee manieren om een HTML-bestand of een pagina te tonen:

De bestandsaanroepen bestaan ook onder /artifacts/{artifact_id}, en /files/{file_id} accepteert het id van een artefact (Wat een bestands-id bereikt).

Beide adressen openen de inhoud zonder sleutel: wie het adres heeft, opent het bestand. Behandel een adres daarom als een geheim. Schrijf het niet in een logregel, zet het niet in een ticket en geef het alleen aan wie het bestand mag lezen.

Een model een HTML-bestand laten schrijven¶

Bied de tool builtin__create_artifact aan om het model een document rechtstreeks als artefact te laten opslaan: een HTML-bestand, een rapport, Markdown of CSV.

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{
      "model": "<een model-id>",
      "input": "Maak een overzicht van de omzet per kwartaal als HTML-bestand.",
      "tools": [{"type": "tool", "name": "builtin__create_artifact"}]
    }'

Je sleutel heeft hiervoor drie dingen nodig: de capability tooling, de capability artifacts, en de kale naam create_artifact onder system_tools in zijn configuratie tooling. In de console is dat het selectievakje Document schrijven op de pagina van de sleutel (Sleutels).

Het model geeft twee argumenten mee, filename en content, en niets anders. De extensie van de bestandsnaam bepaalt het mediatype; het model kiest dat niet zelf:

Alleen een bestand met .html of .htm kun je in een browser openen, delen en als pagina publiceren. Een bestandsnaam met een andere extensie, of zonder extensie, wordt geweigerd, en het model krijgt de lijst met toegestane extensies terug. De inhoud mag niet groter zijn dan de grens van je installatie, standaard 2 MiB; daarboven wordt er niets opgeslagen.

Als het lukt, leest het model Saved <filename> (<n> bytes) as an artifact. Het antwoord zelf noemt het artefact niet, dus zoek het op met GET /artifacts?response_id=resp_... (Artefacten).

Een HTML-bestand moet op zichzelf staan. Eén bestand, met stijlen, scripts en afbeeldingen erin opgenomen, en zonder verzoeken naar buiten: wie het bestand later toont, blokkeert die (Wat een geopend bestand kan). De beschrijving van de tool vertelt het model deze regel al. Vraag je in je eigen instructies om een HTML-bestand, vraag dan niet om een lettertype, een grafiekbibliotheek of een afbeelding van een webadres.

Een HTML-bestand openen¶

Vraag een weergaveadres aan. De aanroep heeft geen body:

curl -s -X POST "$CORE_URL/artifacts/art_8Lp4.../view" \
    -H "Authorization: Bearer $CORE_KEY"

{
  "url": "https://<je Core-adres>/api/v1/views/vt_...",
  "expires_at": "2026-10-06T12:05:00Z"
}

url opent het bestand in een browser tot expires_at. Je installatie bepaalt hoe lang dat is, en het is nooit meer dan vijftien minuten. Tot dat moment werkt het adres zo vaak als het wordt geladen, dus herladen kan. Je kunt een weergaveadres niet intrekken; daarom is het kort geldig. Vraag een nieuw adres aan als het oude is verlopen.

Een adres stopt eerder met werken als de sleutel die het aanvroeg wordt verwijderd of verloopt, als het bestand wordt verwijderd, of als je organisatie is opgeschort of wordt verwijderd.

Toon het bestand op een van deze twee manieren:

• In een eigen tabblad of venster. Dat werkt altijd.
• In een frame in je applicatie: <iframe sandbox="allow-scripts" src="...">. Een browser toont het bestand alleen in een frame op een site die je operator daarvoor heeft toegestaan. Op elke andere site blijft het frame leeg; vraag je operator dan om het adres van je applicatie toe te voegen.

Elke keer dat het adres wordt geopend, schrijft Core artifact.viewed of file.viewed in het auditspoor. Het adres aanvragen schrijft die gebeurtenis niet, en een weergave kost geen gebruik.

Noemt je verzoek een persoon, dan bereikt het de bestanden van die persoon en de gedeelde, zoals bij elke andere aanroep op het bestand.

Wat een geopend bestand kan¶

Een HTML-bestand is inhoud die een model schreef of iemand uploadde, en niemand heeft die gecontroleerd. Core levert het daarom afgeschermd af, wat je eigen frame ook toestaat. Dat geldt voor een weergaveadres en voor een deellink.

De afscherming houdt niet tegen dat de inhoud naar een ander adres vertrekt, met een link of met script:

• In een frame kan de inhoud haar eigen frame naar een ander adres sturen. Het frame toont dan iets van elders op de plek waar het opgeslagen bestand stond. Maak daarom in je applicatie zichtbaar dat het frame opgeslagen inhoud toont.
• In een eigen tabblad, en zo opent een deellink altijd en een weergaveadres als je het zo toont, kan de inhoud dat tabblad naar een ander adres sturen.

Wat met zo'n navigatie meegaat, is wat de inhoud in het adres zette waar ze heen gaat: inhoud die de kijker al kon lezen. Het weergaveadres of de deellink zelf gaat niet mee.

Een HTML-bestand delen¶

Een deellink opent één HTML-bestand voor iemand zonder account, dagenlang, tot de link verloopt of je hem intrekt. Een link op een bestand blijft dat bestand tonen; maak de link op een pagina als hij nieuwe versies moet volgen.

Delen staat standaard uit. Een regel van de soort share_link in het beleid staat het toe, en geen enkel beleidsdocument bevat zo'n regel tenzij iemand hem toevoegt:

• Het beleidsdocument van je organisatie moet het toestaan. Een organisatie zonder eigen document deelt niets, wat de regels van een sleutel ook toestaan.
• Je sleutel deelt alleen als zijn eigen document het ook toestaat.

De regel heeft geen namen, labels of voorwaarden. Naast de regels die een document al bevat, is het één extra ingang in rules, hier getoond met de instelling voor de langste levensduur:

{
  "rules": [
    { "id": "share-link", "effect": "permit", "kind": "share_link" }
  ],
  "settings": { "share_link_max_days": 14 }
}

Stuur dit fragment niet los: een document met alleen deze regel staat verder niets toe. Een beleidsdocument stuur je altijd in zijn geheel, dus lees het eerst, voeg de regel toe en stuur het compleet terug: GET en PUT /organisation/policy voor de organisatie, GET en PATCH /keys/{key_id} met policy voor een sleutel. In de console voegt je beheerder de regel toe in de beleidseditor, als regel Toestaan over Opgeslagen HTML-bestanden en pagina’s delen met een link (Instellingen, Sleutels).

curl -s -X POST "$CORE_URL/files/src_3Wq8.../links" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"expires_in_days": 7}'

Het antwoord is 201 met een Location-header:

{
  "id": "lnk_6Tn2...",
  "object": "share_link",
  "url": "https://<je Core-adres>/api/v1/views/sl_...",
  "file_id": "src_3Wq8...",
  "page_id": null,
  "expires_at": "2026-10-13T09:30:00Z",
  "expired": false,
  "closed": false,
  "created_by": "key_4Hd9...",
  "created_at": "2026-10-06T09:30:00Z"
}

expires_in_days is een heel getal van 1 tot en met 365. De langste levensduur is de beleidsinstelling share_link_max_days: de kortste grens die het document van je organisatie en dat van je sleutel noemen, en 30 dagen als geen van beide er een noemt. Vraag je meer, dan is het antwoord 422. Laat je het veld of de hele body weg, dan krijgt de link de langste levensduur die is toegestaan.

Dezelfde vier aanroepen bestaan onder /artifacts/{artifact_id}/links. Een artefact delen is het downloaden ervan: staat geen regel je sleutel toe artefacten te downloaden, dan is het antwoord 403.

Een deellink opent het bestand bovenaan in een tabblad. Geen enkele site kan het in een frame tonen. Voor de inhoud geldt dezelfde afscherming als bij een weergaveadres (Wat een geopend bestand kan).

Core bewaart het adres niet en stelt het bij elke aanroep opnieuw samen. Twee aanroepen geven daarom een verschillend gespeld url voor dezelfde link. Elk van die adressen opent dezelfde link, en ze sluiten allemaal tegelijk.

url is null in drie gevallen. De link blijft dan leesbaar, met zijn id en expires_at, en je kunt hem intrekken:

• Je sleutel zou deze link nu zelf niet kunnen maken: de regels staan hem delen met een link niet toe, of staan hem artefacten downloaden niet toe. Het adres opent de inhoud zonder sleutel, dus wie het bestand niet mag meenemen, krijgt het adres niet te lezen.
• De aanroep komt van een subject-token en het bestand is gedeeld, niet van die persoon zelf. Zo'n token mag een gedeeld bestand niet delen en leest het adres dus ook niet.
• De link is gesloten (closed: true): de sleutel die hem maakte is verwijderd of verlopen, zie hieronder.

Een subject-token deelt alleen de bestanden van zijn eigen persoon en trekt alleen daarvan links in. Voor een gedeeld bestand is het antwoord 403; doe de aanroep vanuit je backend met je sleutel.

Wat een link sluit¶

Een gesloten adres antwoordt 404, zonder te zeggen waarom.

Een link die een persoon in de console maakte, hoort bij geen sleutel en sluit dus niet met een sleutel.

Elke keer dat een deellink wordt geopend, schrijft Core een gebruiksregel van de soort shared_bytes met de grootte van het bestand, en file.link_viewed of artifact.link_viewed in het auditspoor. Een adres dat niet meer opent, schrijft niets. Wie het adres heeft, kan het zo vaak openen als hij wil; zie je in je gebruik dat een link wordt misbruikt, trek hem dan in.

Een pagina publiceren onder een naam¶

Een rapport wordt bijgewerkt, en elke bijgewerkte versie is een nieuw opgeslagen bestand met een nieuw id. Een adres dat op een bestand is gemaakt, blijft dat ene bestand tonen. Een pagina is een naam boven de gepubliceerde versies van een rapport, met een verwijzing naar de versie die ze nu toont. Publiceer een nieuwe versie en elk weergaveadres en elke deellink van de pagina toont die, op het adres dat mensen al hebben.

De aanroepen voor pagina's vereisen files. Een artefact publiceren vereist ook artifacts.

curl -s -X POST "$CORE_URL/pages" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "rapport-q3", "file_id": "art_8Lp4..."}'

Het antwoord is 201 met een Location-header:

{
  "id": "pg_2Vx7...",
  "object": "page",
  "name": "rapport-q3",
  "current_version": 1,
  "file_id": "art_8Lp4...",
  "created_by": "key_4Hd9...",
  "created_at": "2026-10-06T09:30:00Z",
  "updated_at": "2026-10-06T09:30:00Z"
}

name bestaat uit 1 tot 64 kleine letters, cijfers en koppeltekens en is uniek binnen je organisatie; een naam die al bestaat geeft 409. file_id is het HTML-bestand dat versie 1 wordt; een bestand dat geen HTML is geeft 409. In het antwoord is file_id altijd het bestand van de versie die de pagina nu toont.

Je sleutel bereikt een pagina precies wanneer hij het bestand van de huidige versie bereikt. Een pagina die hij niet bereikt, ontbreekt in GET /pages en geeft 404 op haar id.

De volgende versie publiceren¶

curl -s -X POST "$CORE_URL/pages/pg_2Vx7.../versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"file_id": "art_5Rk1..."}'

Het antwoord is de pagina met een current_version die één hoger is en het nieuwe bestand als file_id. Vanaf dat moment toont elk adres van de pagina de nieuwe versie; wie een adres heeft, hoeft geen nieuw adres te krijgen.

Heeft de pagina een deellink die nog opent, dan wordt een nieuwe versie ook naar buiten gepubliceerd. De aanroeper moet daarom nu mogen delen, volgens de regels van Een HTML-bestand delen; anders is het antwoord 403 en blijft de pagina de versie tonen die ze toonde. Hetzelfde geldt voor terug- of vooruitzetten met PATCH.

Een nieuwe versie moet dezelfde soort bestand zijn als de andere versies van de pagina: een pagina bestaat alleen uit uploads of alleen uit artefacten. Noemen je verzoeken een persoon, dan moet het ook een bestand van dezelfde persoon zijn als de pagina. Al het andere geeft 409.

Versies opvragen en terugzetten¶

curl -s "$CORE_URL/pages/pg_2Vx7.../versions" \
    -H "Authorization: Bearer $CORE_KEY"

Elke versie heeft een number, geteld vanaf 1, het file_id dat ze toont, en wie haar publiceerde en wanneer (created_by, created_at). Een nummer wordt nooit twee keer gebruikt: een versie die je na terugzetten publiceert, krijgt het volgende ongebruikte nummer.

Laat de pagina een andere van haar versies tonen met current_version: een eerdere om terug te zetten, een latere om weer vooruit te gaan:

curl -s -X PATCH "$CORE_URL/pages/pg_2Vx7..." \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"current_version": 1}'

Een nummer dat de pagina niet heeft geeft 422, en een versie waarvan je sleutel het bestand niet bereikt ook.

Dezelfde aanroep hernoemt de pagina met name; stuur één veld of allebei. Een naam die al bestaat geeft 409. Terugzetten en hernoemen veranderen het id van de pagina, haar weergaveadressen en haar deellinks niet.

Een pagina openen en delen¶

# een weergaveadres, minuten geldig
curl -s -X POST "$CORE_URL/pages/pg_2Vx7.../view" \
    -H "Authorization: Bearer $CORE_KEY"

# een deellink, dagen geldig
curl -s -X POST "$CORE_URL/pages/pg_2Vx7.../links" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"expires_in_days": 30}'

Beide antwoorden wat de bestandsaanroepen antwoorden, en elke regel van Een HTML-bestand openen en Een HTML-bestand delen geldt: de regel over artefacten downloaden, de regel over delen met een link, de langste levensduur, een url die null is, wat het geopende bestand kan, en wat er wordt vastgelegd en gemeten. Het verschil is wat het adres toont: de versie die actueel is op het moment dat het adres wordt geopend. Een deellink die je vorige week verstuurde, toont de versie die je vandaag publiceerde.

Een link op een pagina noemt de pagina in page_id, en zijn file_id is het bestand van de versie die de pagina nu toont. Een link op een bestand heeft page_id: null. De links van een pagina vraag je op, lees je en trek je in onder /pages/{page_id}/links, niet onder het bestand dat de pagina op dat moment toont.

In het auditspoor staat een weergave van een pagina als een weergave van het bestand dat ze toonde, met page_id naast het id van het bestand.

Een gepubliceerd bestand blijft bewaard¶

Publiceren zet de retention van het bestand op keep, zodat het bewaarvenster van je organisatie geen bestand verwijdert dat een pagina toont. Dat geldt voor versie 1 en voor elke latere versie.

Zolang een bestand een versie van een pagina is, geven drie aanroepen 409, en de melding noemt de pagina:

• het bestand verwijderen, via /files, /artifacts of de bronnen van een collectie;
• zijn retention terugzetten op window;
• een collectie verwijderen waarin het staat.

Verwijder eerst de pagina.

Een pagina verwijderen¶

curl -s -X DELETE "$CORE_URL/pages/pg_2Vx7..." \
    -H "Authorization: Bearer $CORE_KEY"

204. De naam, de versies en de deellinks van de pagina zijn weg, en elk adres van de pagina opent meteen niet meer. De bestanden blijven, en blijven op keep staan. Verwijder ze met DELETE /files/{file_id}, of zet hun retention terug op window, als je ze niet meer nodig hebt.

Een subject-token publiceert, zet terug, hernoemt en verwijdert alleen een pagina van zijn eigen persoon.

Fouten bij HTML-bestanden en pagina's¶