[{"data":1,"prerenderedAt":124},["ShallowReactive",2],{"docs:it:rest-api":3},{"id":4,"meta":5,"intro":8,"contractVersion":11,"contractVersionLabel":12,"contractNotice":13,"contractDownload":14,"labels":17,"sections":29},"rest-api",{"title":6,"lead":7},"API REST","Tutte le rotte che una chiave API può chiamare, lette dal contratto OpenAPI che viaggia dentro il servizio.",{"title":9,"lead":10},"Riferimento dell’API REST","Che cosa espone l’API, dove sta ogni rotta e che cosa deve portare una chiave per passare.","1.15.0","Versione del contratto","Il riferimento qui sotto è letto dal contratto OpenAPI, che è scritto in inglese. Non è tradotto di proposito: tradurlo vorrebbe dire ricopiarlo, e una copia prima o poi diverge.",{"href":15,"label":16},"\u002Fopenapi.json","Scarica il contratto pubblico (OpenAPI, JSON)",{"method":18,"path":19,"summary":20,"scope":21,"authentication":22,"form":23,"name":24,"type":25,"notes":26,"description":27,"downloadContract":16,"contractVersion":12,"command":28},"Metodo","Percorso","Che cosa fa","Ambito della chiave","Accetta","Sulla richiesta","Nome","Tipo","Note","Descrizione","Comando",[30,39,60],{"id":31,"title":32,"paragraphs":33,"block":38},"overview","Da dove viene questa pagina",[34,35,36,37],"Questo riferimento non è scritto, è letto. Ogni rotta, ogni metodo e ogni ambito qui sotto vengono dal contratto OpenAPI compilato dentro il binario dell’API, e un controllo confronta quel contratto con il codice in esecuzione a ogni build.","Un riferimento tenuto a mano comincia a divergere la settimana dopo essere stato scritto, e da quel momento è peggio di nessun riferimento, perché lo si crede. L’unico modo per non divergere è non avere una seconda copia da cui divergere.","Qui sono elencate le operazioni che una chiave API può chiamare, e nessuna altra. Il resto del servizio la dashboard lo guida con rotte che raggiunge solo una sessione dal browser: non fanno parte dell’API pubblica, cambiano senza preavviso, e documentarle le trasformerebbe in una promessa che nessuno ha fatto.","Qui trovi la superficie: dove sta una rotta e a che cosa serve. Il resto lo porta il contratto — schemi di richiesta e risposta, codici di errore, limiti di frequenza — ed è il documento da leggere quando una chiamata risponde qualcosa che non ti aspettavi. La copia che puoi scaricare contiene le stesse operazioni di questa pagina, e solo quelle.",null,{"id":40,"title":41,"paragraphs":42,"block":46},"authentication","Autenticazione",[43,44,45],"Tre modi di dimostrare chi sei, e non sono intercambiabili. La chiave con ambiti è quella pensata per i programmi; la sessione è quella che il browser tiene mentre usi la dashboard.","Gli ambiti di scrittura non comprendono quelli di lettura. Altrimenti chi guarda una chiave leggerebbe jobs:write e dovrebbe ricordarsi che copre anche la lettura.","Le operazioni che non accettano nessuna chiave — emettere credenziali, impegnare un pagamento, distruggere un account — mancano da questa pagina esattamente per questo. È una decisione e non una dimenticanza: una chiave capace di crearne un’altra renderebbe inutile revocare la prima.",{"kind":47,"schemes":48},"schemes",[49,53,57],{"name":50,"form":51,"description":52},"sessionCookie","Cookie: pq_session=…","Browser session (R14). HttpOnly: the token is out of reach of JavaScript, so an XSS on the dashboard cannot carry it away.",{"name":54,"form":55,"description":56},"sessionBearer","Authorization: Bearer …","The same session token, for clients without a cookie jar. When both arrive, the cookie wins — it is the session the user expects to be using.",{"name":58,"form":55,"description":59},"apiKey","Scoped API key (R9): Authorization: Bearer pq_live_.... The prefix is what tells it apart from a session token without having to try both. The scope each operation requires is declared in x-api-key-scope, and it is compared against the code on every CI run. Write scopes do not imply read scopes: otherwise someone looking at a key's scopes would see jobs:write and have to remember that it covers reading too. Operations that do not declare this scheme do not accept a key, ever: they are the ones that issue credentials, commit to a payment, or destroy the account.",{"id":61,"title":62,"paragraphs":63,"block":65},"operations","Operazioni",[64],"Raggruppate come le raggruppa il contratto. Un pezzo di percorso fra parentesi graffe è un parametro da sostituire; la colonna dell’ambito dice che cosa deve portare una chiave perché quella chiamata passi.",{"kind":61,"groups":66},[67,115],{"name":68,"description":69,"operations":70},"jobs","Cron jobs and executions (R8).",[71,77,82,86,90,94,99,103,107,111],{"method":72,"path":73,"summary":74,"scope":75,"security":76},"GET","\u002Fjobs","List jobs (R8)","jobs:read",[50,54,58],{"method":78,"path":73,"summary":79,"scope":80,"security":81},"POST","Create a job (R1, R8)","jobs:write",[50,54,58],{"method":72,"path":83,"summary":84,"scope":75,"security":85},"\u002Fjobs\u002F{id}","Read one job",[50,54,58],{"method":87,"path":83,"summary":88,"scope":80,"security":89},"PATCH","Partially update a job",[50,54,58],{"method":91,"path":83,"summary":92,"scope":80,"security":93},"DELETE","Delete a job",[50,54,58],{"method":72,"path":95,"summary":96,"scope":97,"security":98},"\u002Fjobs\u002F{id}\u002Fexecutions","Execution log (R6)","executions:read",[50,54,58],{"method":78,"path":95,"summary":100,"scope":101,"security":102},"Run now (R8)","executions:trigger",[50,54,58],{"method":72,"path":104,"summary":105,"scope":97,"security":106},"\u002Fjobs\u002F{id}\u002Fexecutions\u002Fstream","Execution log in real time (SPEC §4.2)",[50,54,58],{"method":72,"path":108,"summary":109,"scope":97,"security":110},"\u002Fexecutions\u002Fexport","Download the execution log (R27)",[50,54,58],{"method":72,"path":112,"summary":113,"scope":97,"security":114},"\u002Fexecutions\u002Fmetrics","Duration, failure rate and trend (R28)",[50,54,58],{"name":116,"description":117,"operations":118},"secrets","Workspace secrets resolved at execution time (R42, R43).",[119],{"method":72,"path":120,"summary":121,"scope":122,"security":123},"\u002Fsecrets","List workspace secrets (R42)","secrets:read",[50,54,58],1788438713237]