Publiceren en installeren via de API¶

Het concept achter publicaties staat in Delen en hergebruik.

Een sleutel met de capability management doet alles wat een beheerder in de console doet met een bundel: publiceren, installeren, synchroniseren en een gekopieerd onderdeel losmaken (Organisaties beheren via de API laat zien hoe je die capability aanzet). De routes hier komen in dezelfde twee vormen: een pad zonder organisatie erin gaat over je eigen organisatie, en een pad dat er een noemt (/organisations/{id}/...) gaat over een organisatie onder je.

Voor een bundel die als bestanden in een repository staat, roept het commando artific deze routes voor je aan: Een bundel uitbrengen met het artific-commando.

Publiceren¶

POST /publications maakt het aanbod aan — een naam, wie hem mag zien (visibility) en of hij meteen listed is:

curl -s -X POST "$CORE_URL/publications" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "starter-bundel", "visibility": "subtree", "status": "listed"}'

PATCH /publications/{pid} wijzigt de beschrijving en alleen de beschrijving: de naam en de zichtbaarheid blijven zoals ze waren, en een body die er een noemt wordt geweigerd. Bij een app die al in de marktplaats staat verschijnt de nieuwe tekst als pending_description in je eigen reads en gaat hij live zodra Artific na zijn beoordeling de eerstvolgende versie van de app vrijgeeft.

POST /publications/{pid}/versions publiceert een versie — uit rijen van je eigen bibliotheek, of als kant-en-klaar manifest:

curl -s -X POST "$CORE_URL/publications/pub_4Kd9.../versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"members": [{"kind": "prompt", "id": "prm_9Fb2..."}]}'

GET /publications, GET /publications/{pid} en de covers ernaast beantwoorden precies wat de console over jouw eigen aanbod laat zien; GET /publications/{pid}/entitlements laat zien wie er recht op heeft. POST .../submit vraagt Artific om een catalogue-publicatie te beoordelen; het beoordelen zelf blijft aan Artific, net als de recensie-wachtrij van GET /catalogue.

Installeren¶

GET /available-publications toont wat je organisatie mag installeren; POST /subscriptions installeert er een:

curl -s -X POST "$CORE_URL/subscriptions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"publication_id": "pub_4Kd9..."}'

Ontbreekt er een verplichte parameterwaarde, dan komt het abonnement op needs_configuration te staan in plaats van te weigeren; PATCH /subscriptions/{sid} levert de waarde na, en PATCH .../secrets een credential apart. Een bundel die mensen laat inloggen via een OAuth-applicatie die deze installatie niet heeft ingesteld, wacht ook op needs_configuration, met last_error unconfigured_client:<naam> (de preview noemt de naam onder clients.unconfigured); vraag je beheerder die applicatie in te stellen en stuur daarna PATCH /subscriptions/{sid} met de body {} om opnieuw te controleren en de installatie te starten. GET /subscriptions, GET .../{sid} en POST .../preview (wat installeren zou betekenen, zonder iets te schrijven) werken hetzelfde als in de console.

Synchroniseren en losmaken¶

POST /subscriptions/{sid}/sync vraagt direct om de synchronisatie die een nieuwe versie, een nieuwe config of een nieuwe credential anders zelf in gang zou zetten:

curl -s -X POST "$CORE_URL/subscriptions/sub_1Ac7.../sync" \
    -H "Authorization: Bearer $CORE_KEY"

Staat het abonnement niet op linked, diverged of stale, dan antwoordt dit 409 met een vaste code (sync_not_now:<status>) in plaats van een zin. POST .../members/{member}/fork maakt één onderdeel los van de publicatie, zodat jouw organisatie het zelf mag wijzigen; de naam is die van het onderdeel in het manifest, niet zijn id. DELETE /subscriptions/{sid} zegt het abonnement op.

Prompts in een bundel¶

De definitie van een promptlid is de body van POST /prompts/{id}/versions: template, input_schema, role en install_values, plus de eigen metadata van de prompt. Een veld labels wordt geaccepteerd en genegeerd; de kopie komt zonder labels binnen. Publiceren vanuit rijen ({"kind": "prompt", "id": "prm_..."} in members) neemt de laatste gepubliceerde versie van de prompt, nooit een concept, en maakt van de invulwaarden parameters van de bundel, met jouw eigen waarde als standaard voor wie installeert.

Wat een geïnstalleerde promptkopie meeneemt¶

• Naam. Het prefix van het abonnement, gevolgd door de naam van het onderdeel.
• Metadata. Die van de uitgever. Elke synchronisatie die de kopie schrijft (een nieuwe publicatieversie, of een gewijzigde config) vervangt de metadata van de kopie in zijn geheel door die van het onderdeel; een onderdeel zonder metadata laat {} achter. Zolang de kopie gekoppeld is, kun je die zelf niet wijzigen: een nieuwe versie van een gekoppelde kopie is 409.
• Labels. Geen. Labels reizen nooit mee: de kopie komt ongeclassificeerd binnen, en geen synchronisatie schrijft haar labels.
• Versies. Een eigen reeks. Elke synchronisatie die de kopie schrijft, voegt haar volgende versie toe (1, 2, 3), welke publicatieversie die ook opleverde.

Een verzegelde promptkopie¶

Verbergt de uitgever de inhoud, dan verbergt het zegel de template en de variabelen van elke versie die eronder is geïnstalleerd, en verder niets. GET /prompts/{id} en de versieroutes geven zo'n versie terug met:

Ook de name, de metadata en de origin van de prompt blijven leesbaar. Een beurt rendert de versie ongewijzigd, dus een verzegelde prompt kun je draaien maar niet lezen. Een verzegelde kopie kun je niet losmaken, en POST /prompts/{id}/copy weigert haar met 403.

Scripts in een bundel¶

Een script kan lid zijn van een bundel, net als een prompt of een koppeling. Wie installeert, krijgt een kopie in de eigen bibliotheek, die aan de eigen modellen wordt aangeboden als script__<voorvoegsel><naam>.

Wat een scriptlid bevat¶

De definitie van een scriptlid is de body van POST /scripts zonder name en labels: een kopie komt ongeclassificeerd aan, zoals elke kopie. De bestanden van het script reizen niet in het manifest mee. Elk item van files noemt een bestand met path, size_bytes en sha256, en de bytes worden naast de publicatie bewaard, op digest:

curl -s -X PUT "$CORE_URL/publications/pub_4Kd9.../files/$(sha256sum sjabloon.pptx | cut -d' ' -f1)" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/octet-stream" \
    --data-binary @sjabloon.pptx

De route controleert of de bytes de digest uit het pad hebben (anders 422 op sha256), en hetzelfde bestand nog eens aanbieden schrijft niets. GET op hetzelfde pad zegt of de publicatie het bestand al heeft; 404 betekent dat je het nog moet uploaden. De grenzen:

• één bestand hoogstens 32 MiB; een grotere upload geeft 413;
• de scriptbestanden en meegebrachte pakketten van één versie samen hoogstens 128 MiB; daarboven geeft de versie 422 op members;
• alle bestanden van één publicatie samen hoogstens 1 GiB; daarboven geeft een upload of een publicatie 409.

Je operator kan ze aanpassen.

Met de hand uploaden hoeft zelden:

• Publiceren vanuit rijen ({"kind": "script", "id": "scr_..."} in members) neemt de laatste versie van het script en kopieert de bestanden zelf naar de publicatie.
• Een manifest publiceren vraagt dat elk bestand eerst geüpload is. Een item waarvan de publicatie de digest niet heeft, geeft 422 op members.<i>.definition.files.<j>.sha256.

Een toolset, alias of agent in dezelfde bundel noemt het script als {"$member": "huisstijl_presentatie", "kind": "script"}, wat de eigen kopie van de abonnee wordt. De bestanden van een gepubliceerde versie lees je terug via GET /publications/{pid}/versions/{v}/members/script/{member}/files/{path}.

Pakketten in een bundel¶

Wat er met een pakket gebeurt dat een script noemt, hangt af van wie het goedkeurde:

• Een bibliotheek uit de image, of een pakket dat je operator voor de installatie goedkeurde, reist alleen op naam mee. De abonnee zit op dezelfde installatie, dus de kopie vindt dezelfde goedkeuring.
• Een pakket dat alleen jouw organisatie goedkeurde, reist met de bundel mee: het lid noemt het met zijn bestand (ecosystem, name, version, filename, size_bytes, sha256), en het bestand wordt naast de publicatie bewaard, net als de eigen bestanden van het script. Publiceren vanuit rijen kopieert het voor je.

De abonnee ziet deze pakketten vóór het installeren: packages in de preview noemt elk pakket met ecosysteem, naam, versie, bestand en digest, ook als de bundel zijn inhoud verbergt. Installeren is de goedkeuring. Het pakket wordt alleen voor dat gekopieerde script geïnstalleerd, staat op de versies van de kopie als approval: bundle, en komt nooit in de eigen lijst met goedgekeurde pakketten van de abonnee. Diens beheerders beslissen nog steeds zelf wat hun eigen scripts mogen gebruiken.

Een latere versie waarin een script een pakket meebrengt dat het eerder niet meebracht (een nieuwe naam, een nieuwe versie, of andere bytes), wacht op de abonnee, net als gewijzigde voorwaarden: het abonnement gaat naar needs_acceptance en de kopie blijft draaien wat ze draaide. Bekijk die versie eerst, met de eigen prefix en config van het abonnement zodat het rapport bij je installatie past, en accepteer dan:

curl -s -X POST "$CORE_URL/subscriptions/preview" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"publication_id": "pub_4Kd9...", "follow": "pinned", "pinned_version": 4,
         "prefix": "acme-", "config": {"bedrijf": "Acme"}}'

curl -s -X PATCH "$CORE_URL/subscriptions/sub_1Ac7..." \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"accept_terms_version": 4}'

Een versie die een pakket laat vallen, of alleen al geaccepteerde pakketten meebrengt, installeert zoals elke andere.

Een script installeren¶

Een bundel met een script vraagt tooling en computer in de organisatie van de abonnee. Staat de organisatie computer niet toe, dan wordt het abonnement geweigerd met 422: geen sleutel daar zou het script kunnen draaien.

• Gekoppeld. Zolang de kopie de publicatie volgt, verandert alleen de publicatie haar: een nieuwe versie of het verwijderen van de kopie is 409, met de naam van de publicatie. Elke nieuwe publicatieversie die verandert wat het script draait, wordt een nieuwe versie van de kopie.
• Losgemaakt. POST .../members/{member}/fork maakt de kopie los, als de voorwaarden dat toestaan. Vanaf dan is het een gewoon script van jou en volgt het geen nieuwe versies.
• Verzegeld. Verbergt de uitgever de inhoud, dan kun je de kopie draaien maar niet lezen: de leesroutes geven de naam, de beschrijving en de parameters, met entrypoint als null en files leeg, en de bestandsroute geeft 404. Een verzegelde kopie kun je niet losmaken en niet opnieuw publiceren. In een beurt draait ze op een eigen computer, los van de computer die de shell-tools van het model gebruiken, zodat niets in de beurt haar bestanden kan lezen; die tweede computer kost sandboxtijd zoals de eerste.

Voor een organisatie onder je¶

Elke route hierboven bestaat ook onder /organisations/{id}/..., voor een organisatie die je met management bereikt:

curl -s -X POST "$CORE_URL/organisations/ten_9Fb2.../subscriptions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"publication_id": "pub_4Kd9..."}'

Dit is een beheershandeling over de bibliotheek van die organisatie — net als het aanmaken van een sleutel daar — en geen manier om haar prompts, skills of kennis rechtstreeks te lezen: dat blijft een sleutel die je in die organisatie registreert (Werken in een organisatie onder je).

De marktplaats¶

GET /marketplace toont wat Artific voor de hele installatie heeft goedgekeurd — het pad heet anders dan de console's GET /catalogue, omdat elke route hier één padruimte deelt en dat pad al bestaat. De recensiewachtrij zelf (?status=submitted in de console) is er niet: die is aan Artific alleen.