{"components":{"parameters":{"AppID":{"in":"path","name":"app_id","required":true,"schema":{"type":"string"}},"Cursor":{"description":"The next_cursor of the previous page.","in":"query","name":"cursor","schema":{"type":"string"}},"JobID":{"in":"path","name":"job_id","required":true,"schema":{"type":"string"}},"Limit":{"description":"Items per page, 1 to 200.","in":"query","name":"limit","schema":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"VersionID":{"in":"path","name":"version_id","required":true,"schema":{"type":"string"}}},"responses":{"Error":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A refused request. The status carries the class and error.code the reason: invalid_request (400), package_refused (400, with the diagnostics), not_authenticated (401, with WWW-Authenticate), insufficient_scope (403), not_found (404, for an app or job the caller cannot reach), draft_changed, schema_conflict, review_stale, or conflict (409), create_pending (409, retryable with Retry-After, for a push to an app whose create job has not finished), billing.upgrade_required (402, permanent until the app owner changes plan or usage), payload_too_large (413), rate_limited (429, with Retry-After), quota (429, for a build limit, or retryable with Retry-After), and compiler_busy or unavailable (503, retryable)."}},"schemas":{"App":{"additionalProperties":false,"properties":{"access":{"enum":["private","shared","public"],"type":"string"},"app_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"draft_version_id":{"description":"Empty before the first version, and for a caller who does not design the app.","type":"string"},"live_version_id":{"description":"Empty until the first publish.","type":"string"},"name":{"type":"string"},"url":{"description":"The app's origin, or empty while it has no address.","type":"string"}},"required":["app_id","name","url","access","draft_version_id","live_version_id","created_at"],"type":"object"},"AppList":{"additionalProperties":false,"properties":{"apps":{"items":{"$ref":"#/components/schemas/App"},"type":"array"},"next_cursor":{"description":"Empty on the last page.","type":"string"}},"required":["apps","next_cursor"],"type":"object"},"Check":{"additionalProperties":false,"properties":{"candidate_hash":{"description":"The hash of the stored package.","type":"string"},"diagnostics":{"description":"Empty for a stored version.","items":{"$ref":"#/components/schemas/Diagnostic"},"type":"array"},"passed":{"type":"boolean"},"skill_identity":{"description":"The identity of the app contract the package was checked against.","type":"string"},"truncated":{"description":"Always false for a stored version.","type":"boolean"}},"required":["passed","candidate_hash","diagnostics","truncated","skill_identity"],"type":"object"},"Diagnostic":{"additionalProperties":false,"properties":{"code":{"description":"The diagnostic code.","type":"string"},"file":{"description":"The file as the client sent it.","type":"string"},"message":{"type":"string"}},"required":["code","file","message"],"type":"object"},"Error":{"additionalProperties":false,"properties":{"error":{"additionalProperties":false,"properties":{"code":{"type":"string"},"diagnostics":{"description":"Present on package_refused, the first reasons the package fails, at most 50 and 64 KiB of them as JSON.","items":{"$ref":"#/components/schemas/Diagnostic"},"type":"array"},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"truncated":{"description":"Present and true on package_refused when the scan found more diagnostics than the error lists, or shortened one.","type":"boolean"}},"required":["code","message","retryable","request_id"],"type":"object"}},"required":["error"],"type":"object"},"Job":{"additionalProperties":false,"properties":{"app_id":{"description":"The app a push targets, or the one a create made once it exists.","type":"string"},"error":{"oneOf":[{"$ref":"#/components/schemas/JobError"},{"type":"null"}]},"job_id":{"type":"string"},"kind":{"enum":["create","push"],"type":"string"},"poll_after_seconds":{"description":"Zero once the job finished.","type":"integer"},"result":{"oneOf":[{"$ref":"#/components/schemas/JobResult"},{"type":"null"}]},"state":{"enum":["queued","running","done","failed"],"type":"string"}},"required":["job_id","kind","state","app_id","poll_after_seconds","result","error"],"type":"object"},"JobAccepted":{"additionalProperties":false,"properties":{"job_id":{"type":"string"},"poll_after_seconds":{"type":"integer"},"status_url":{"format":"uri","type":"string"}},"required":["job_id","status_url","poll_after_seconds"],"type":"object"},"JobError":{"additionalProperties":false,"properties":{"code":{"description":"package_refused, draft_changed, design_revoked (the pushing account lost design access after the push was accepted), schema_conflict, quota, conflict, not_found, invalid_request, compiler_busy, or unavailable.","type":"string"},"diagnostics":{"description":"The first diagnostics the check found, at most 50 and 64 KiB of them as JSON.","items":{"$ref":"#/components/schemas/Diagnostic"},"type":"array"},"message":{"type":"string"},"skill_identity":{"description":"The identity of the app contract the job's check ran against, as a done job reports it, so a client can tell a stale copy of the contract from a broken package. Empty when the job failed before its package was checked.","type":"string"},"truncated":{"description":"Whether the check found more diagnostics than the job kept.","type":"boolean"}},"required":["code","message","diagnostics","truncated","skill_identity"],"type":"object"},"JobResult":{"additionalProperties":false,"properties":{"app_id":{"type":"string"},"check":{"$ref":"#/components/schemas/Check"},"version":{"$ref":"#/components/schemas/Version"}},"required":["app_id","version","check"],"type":"object"},"Live":{"additionalProperties":false,"properties":{"app_id":{"type":"string"},"live_version_id":{"type":"string"},"url":{"format":"uri","type":"string"}},"required":["app_id","live_version_id","url"],"type":"object"},"Me":{"additionalProperties":false,"properties":{"account_id":{"type":"string"},"email":{"type":"string"},"username":{"description":"Empty until the person claims one on the platform.","type":"string"}},"required":["account_id","username","email"],"type":"object"},"Package":{"additionalProperties":{"type":"string"},"description":"UTF-8 text files by relative path. An image under assets/ (.png, .jpg, .jpeg or .webp) is sent as standard base64 text; a multipart upload sends its bytes as they are. At most 400 files, 256 KiB each, 10 MiB in all. A files object with more than 400 files, a file over 256 KiB, 10 MiB of contents, or a path over 128 bytes is refused as 413 payload_too_large while it is read, and a path no package may hold, a path named twice, or a top-level member named twice as 400 invalid_request; a request body that is not valid UTF-8 is 400 invalid_request too; the other bounds are package diagnostics. Too many package uploads at once answer 429 rate_limited with Retry-After.","minProperties":1,"type":"object"},"PackageRequest":{"additionalProperties":false,"description":"A package without index.html gets a default shell titled with the app's name.","properties":{"app_id":{"description":"The app to push a new draft to. Leave it out to create an app.","maxLength":128,"type":"string"},"files":{"$ref":"#/components/schemas/Package"},"name":{"description":"Required to create an app, refused with app_id. The address is derived from it. NUL and hyphens are refused; use spaces instead.","maxLength":60,"minLength":1,"type":"string"},"summary":{"description":"What this version changes, in at most 240 characters, without NUL. Defaults to \"Submitted a package.\".","maxLength":240,"type":"string"}},"required":["files"],"type":"object"},"PackageUpload":{"description":"The same fields as PackageRequest as form parts. Each files part carries one file; its filename is the package path, such as app.ts or lib/store.ts.","properties":{"app_id":{"type":"string"},"files":{"items":{"format":"binary","type":"string"},"type":"array"},"name":{"type":"string"},"summary":{"type":"string"}},"required":["files"],"type":"object"},"Preview":{"additionalProperties":false,"properties":{"app_origin":{"format":"uri","type":"string"},"expires_at":{"format":"date-time","type":"string"},"preview_url":{"format":"uri","type":"string"}},"required":["preview_url","app_origin","expires_at"],"type":"object"},"PublishRequest":{"additionalProperties":false,"properties":{"review_token":{"description":"The review_token the review answered. Leave it out to read the review.","type":"string"}},"type":"object"},"PublishReview":{"additionalProperties":false,"properties":{"access":{"enum":["private","shared","public"],"type":"string"},"draft_version_id":{"type":"string"},"link_enabled":{"type":"boolean"},"link_role":{"description":"viewer, editor, or empty when the app has no join link.","type":"string"},"live_url":{"description":"The app's origin, or empty while it has no address.","type":"string"},"live_version_id":{"type":"string"},"member_count":{"type":"integer"},"name":{"description":"The app's current name, so a confirmation can label the app without library:read.","type":"string"},"public_role":{"description":"What a signed-in visitor who is not a member may do while access is public; editor visitors change shared data.","enum":["viewer","editor"],"type":"string"},"review_token":{"type":"string"},"summary":{"type":"string"},"version_number":{"type":"integer"}},"required":["review_token","name","draft_version_id","version_number","summary","live_url","access","public_role","member_count","link_role","link_enabled","live_version_id"],"type":"object"},"Version":{"additionalProperties":false,"properties":{"created_at":{"format":"date-time","type":"string"},"live":{"description":"Whether the version is live now.","type":"boolean"},"number":{"type":"integer"},"package_hash":{"type":"string"},"published":{"description":"Whether the version was ever live.","type":"boolean"},"source":{"type":"string"},"summary":{"type":"string"},"version_id":{"type":"string"}},"required":["version_id","number","package_hash","summary","source","created_at","published","live"],"type":"object"},"VersionIDRequest":{"additionalProperties":false,"properties":{"version_id":{"description":"A version's id. NUL and invalid UTF-8 are refused.","maxLength":128,"minLength":1,"type":"string"}},"required":["version_id"],"type":"object"},"VersionList":{"additionalProperties":false,"properties":{"live_version_id":{"type":"string"},"next_cursor":{"type":"string"},"versions":{"items":{"$ref":"#/components/schemas/Version"},"type":"array"}},"required":["versions","live_version_id","next_cursor"],"type":"object"},"VersionRead":{"additionalProperties":false,"properties":{"compiled_files":{"additionalProperties":{"type":"string"},"description":"The files the app serves.","type":"object"},"created_at":{"format":"date-time","type":"string"},"files":{"additionalProperties":{"type":"string"},"description":"The files the version was accepted from.","type":"object"},"live":{"type":"boolean"},"number":{"type":"integer"},"package_hash":{"type":"string"},"published":{"type":"boolean"},"source":{"type":"string"},"source_hash":{"type":"string"},"source_provenance":{"enum":["exact","reconstructed"],"type":"string"},"summary":{"type":"string"},"version_id":{"type":"string"}},"required":["version_id","number","package_hash","summary","source","created_at","published","live","source_hash","source_provenance","files","compiled_files"],"type":"object"}},"securitySchemes":{"bearer":{"description":"The access token the client's OAuth sign-in issued. Scopes are granted at sign-in; each route lists the scopes it accepts.","scheme":"bearer","type":"http"}}},"info":{"description":"JSON over HTTPS at /v1 for an agent that creates, pushes, previews, publishes, and rolls back apps on a person's behalf. Every route but this document takes the OAuth bearer a client obtained for the person. Requests and responses use snake_case; unknown request fields are refused. Every response carries X-Request-Id; every admitted response carries X-RateLimit-Limit and X-RateLimit-Remaining.","title":"iqobi agent API","version":"1.0.0-alpha.1"},"openapi":"3.1.0","paths":{"/v1/apps":{"get":{"description":"Newest first. Pass next_cursor as cursor for the next page.","operationId":"listApps","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppList"}}},"description":"One page of apps"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["library:read"]}],"summary":"The apps the account owns"},"post":{"description":"Without app_id, creates an app from the package (needs apps:create and a username): the package is checked, the app is created under an address derived from its name, and the package becomes version one. With app_id, pushes the package as the app's next draft (needs studio:write); if the draft changes before the version commits, the job fails with draft_changed. Either way the work runs as a job, and each request makes a new job. Send multipart/form-data with one files part per file, its filename the package path, or a JSON PackageRequest. When too many jobs are unfinished the request is quota (429) with a Retry-After.","operationId":"submitPackage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PackageUpload"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}},"description":"The job that creates the app or stores the version"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["apps:create"]},{"bearer":["studio:write"]}],"summary":"Create an app, or push a new version of one"}},"/v1/apps/{app_id}":{"get":{"description":"The app, its draft and live version ids, address, and access level. A designer sees the draft id; anyone else sees an empty one.","operationId":"getApp","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/App"}}},"description":"The app"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["library:read"]}],"summary":"One app"},"parameters":[{"$ref":"#/components/parameters/AppID"}]},"/v1/apps/{app_id}/previews":{"parameters":[{"$ref":"#/components/parameters/AppID"}],"post":{"description":"A link on the platform origin that opens the version's preview for three minutes, bound to the bearer's client session. A new link replaces the previous one.","operationId":"createPreview","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionIDRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}},"description":"The preview link"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["studio:read"]}],"summary":"A short-lived preview link"}},"/v1/apps/{app_id}/publish":{"parameters":[{"$ref":"#/components/parameters/AppID"}],"post":{"description":"Owner only. Without review_token, answers the review of the draft and the audience it will reach, with a review_token; show it to the person. With that review_token, the draft goes live. A changed draft or audience since the review answers review_stale. Publishing never changes who can open the app. A proposal workspace is never published here and answers 400 invalid_request; the app's owner reviews the proposal.","operationId":"publishApp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PublishReview"},{"$ref":"#/components/schemas/Live"}]}}},"description":"The review when the request has no review_token, otherwise the app as it now serves"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["apps:publish"]}],"summary":"Review the draft, then publish it"}},"/v1/apps/{app_id}/rollback":{"parameters":[{"$ref":"#/components/parameters/AppID"}],"post":{"description":"Owner only. The version must have been published. A version that is live already answers 200 and changes nothing, so a retry after a committed rollback reads the same answer.","operationId":"rollbackApp","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionIDRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Live"}}},"description":"The app as it now serves"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["apps:publish"]}],"summary":"Make a version that was live before live again"}},"/v1/apps/{app_id}/versions":{"get":{"description":"Newest first, with whether each was ever published and which is live now.","operationId":"listVersions","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionList"}}},"description":"One page of versions"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["studio:read"]}],"summary":"The app's versions"},"parameters":[{"$ref":"#/components/parameters/AppID"}]},"/v1/apps/{app_id}/versions/{version_id}":{"get":{"description":"files holds the files the version was accepted from; push them back as they are, or push compiled_files when files holds .jsx, .tsx, .mts, or .cts sources, which a push refuses. compiled_files holds what the app serves. source_provenance is reconstructed when files could not be read back exactly. Too many reads at once answer 429 with Retry-After.","operationId":"getVersion","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionRead"}}},"description":"The version with its source and compiled files"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["studio:read"]}],"summary":"One version, its source, and its compiled files"},"parameters":[{"$ref":"#/components/parameters/AppID"},{"$ref":"#/components/parameters/VersionID"}]},"/v1/jobs/{job_id}":{"get":{"description":"Poll every poll_after_seconds while queued or running. A finished job stays readable for one day. studio:read reads every job of the account; apps:create reads its create jobs and studio:write its push jobs, so the credential that submitted a job can poll it.","operationId":"getJob","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"description":"The job"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["studio:read"]},{"bearer":["apps:create"]},{"bearer":["studio:write"]}],"summary":"Where a create or push got to"},"parameters":[{"$ref":"#/components/parameters/JobID"}]},"/v1/me":{"get":{"operationId":"getAccount","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}},"description":"The account behind the bearer"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}},"security":[{"bearer":["account:read"]}],"summary":"The signed-in account"}},"/v1/openapi.json":{"get":{"description":"Cacheable for five minutes: Cache-Control: public, max-age=300.","operationId":"getOpenAPI","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"The OpenAPI document"}},"security":[],"summary":"This document as JSON"}}},"security":[{"bearer":[]}],"servers":[{"url":"https://api.iqobi.com"}]}
