{"openapi":"3.1.0","info":{"title":"Praecise Cloud API","version":"1.0.0","description":"Deploy, roll back and watch your projects.\n\nSend a token as \"Authorization: Bearer prc_cloud_…\". Create one on the Account page of the console: choose its projects, its scopes (read, deploy, rollback, env) and how long it lasts (90 days unless you say, 365 at most).\n\nA token never does more than the person who made it. On a project, a member can read, deploy and roll back; an owner can also change the environment and read the audit trail.\n\nEvery answer is JSON. A refusal is {\"error\": \"a plain sentence\", \"code\": \"a_word\"}. Times are seconds since 1970."},"servers":[{"url":"https://console.praecise.cloud"}],"paths":{"/api/whoami":{"get":{"operationId":"whoami","summary":"Who this token is, and what it carries.","security":[{"token":["read"]}],"x-scope":"read","responses":{"200":{"description":"The caller.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects":{"get":{"operationId":"listProjects","summary":"The projects the caller can see.","security":[{"token":["read"]}],"x-scope":"read","responses":{"200":{"description":"A list of projects.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}":{"get":{"operationId":"getProject","summary":"One project: domains, live release, service, kept releases, env key names, recent deploys.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}}],"responses":{"200":{"description":"The project.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/releases":{"get":{"operationId":"listReleases","summary":"The releases kept for the project, newest first, and which one is live.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}}],"responses":{"200":{"description":"Kept releases.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/deploys":{"get":{"operationId":"listDeploys","summary":"Recent deploys, newest first.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}}],"responses":{"200":{"description":"Deploys.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/deploys/{id}":{"get":{"operationId":"getDeploy","summary":"One deploy: running, succeeded or failed, and its log so far.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"id","in":"path","required":true,"description":"A deploy id, as returned when the deploy was started.","schema":{"type":"string"}}],"responses":{"200":{"description":"The deploy and its log.","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/logs":{"get":{"operationId":"getLogs","summary":"The last lines the project's service wrote.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"lines","in":"query","required":false,"description":"How many lines, 1 to 2000. 200 when not said.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Log lines, oldest first.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/verify":{"get":{"operationId":"verifyDomain","summary":"Check that one of the project's domains answers.","security":[{"token":["read"]}],"x-scope":"read","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"host","in":"query","required":true,"description":"One of the project's domains.","schema":{"type":"string"}}],"responses":{"200":{"description":"Whether it answers, and what was seen.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/audit":{"get":{"operationId":"getAudit","summary":"Who changed what on the project, newest first, with how each change arrived (session, token or agent), the token id and the address.","security":[{"token":["read"]}],"x-scope":"read","x-role":"owner","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"limit","in":"query","required":false,"description":"How many entries, 1 to 200. 50 when not said.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Audit entries.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/deploy":{"post":{"operationId":"deploy","summary":"Start a deploy of the project from its source. Answers at once with a job; follow it at /api/projects/{name}/deploys/{id}. One deploy runs at a time.","security":[{"token":["deploy"]}],"x-scope":"deploy","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Send the same key when retrying. Within 24 hours the first successful answer is returned again, with Idempotent-Replayed: true, instead of running twice.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"responses":{"202":{"description":"The deploy has started.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A deploy is already running for the project, or the first request with this Idempotency-Key has not finished. Code deploy_running, no_source or request_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request. Code idempotency_key_reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/restart":{"post":{"operationId":"restart","summary":"Restart the project's service on its live release.","security":[{"token":["deploy"]}],"x-scope":"deploy","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}}],"responses":{"200":{"description":"The service was restarted.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/rollback":{"post":{"operationId":"rollback","summary":"Serve a kept release again. Answers when the release is live and healthy, which can take a few minutes; allow five. Anything that is not a kept release answers 400.","security":[{"token":["rollback"]}],"x-scope":"rollback","x-role":"member","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Send the same key when retrying. Within 24 hours the first successful answer is returned again, with Idempotent-Replayed: true, instead of running twice.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["release"],"properties":{"release":{"type":"string","description":"A release id from the kept releases, or \"previous\" for the release that was live before the current one."}}}}}},"responses":{"200":{"description":"The release is live.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A deploy is already running for the project, or the first request with this Idempotency-Key has not finished. Code deploy_running, no_source or request_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The Idempotency-Key was already used for a different request. Code idempotency_key_reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"The rollback did not complete; the answer carries its output. Code rollback_failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/projects/{name}/env":{"post":{"operationId":"setEnv","summary":"Set or clear environment values. Values are never read back, only key names. The service restarts.","security":[{"token":["env"]}],"x-scope":"env","x-role":"owner","parameters":[{"name":"name","in":"path","required":true,"description":"The project's name.","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,62}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"set":{"type":"object","additionalProperties":{"type":"string"},"description":"Keys to set, with their values."},"clear":{"type":"array","items":{"type":"string"},"description":"Keys to remove."}}}}}},"responses":{"200":{"description":"The environment was changed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The token lacks the scope, the call is not open to tokens, or the caller is not an owner. Code scope_missing, session_required or owner_required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such project, or one the caller cannot see. The two are not told apart. Code not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/mcp":{"post":{"operationId":"mcp","summary":"The same API for agents, as MCP over Streamable HTTP (JSON-RPC 2.0). Tools: list_projects, status, list_releases, deploy, deploy_status, rollback, logs. Each tool needs the scope and role of the route it stands for.","security":[{"token":["read"]}],"x-scope":"read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 message."}}}},"responses":{"200":{"description":"A JSON-RPC 2.0 answer. A notification answers 202 with no body.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"The request is not valid: a bad parameter, or a release that is not kept. Code bad_request or bad_release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"No token, or the token is unknown, revoked or expired. Code unauthenticated, token_revoked or token_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many requests for this token. Retry-After says how many seconds to wait. Code rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"token":{"type":"http","scheme":"bearer","description":"A Praecise Cloud token, prc_cloud_…"}},"schemas":{"Problem":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}