Penv Cloud API
HTTP API for reading and writing the values in one penv.cloud project and environment: base URL, operation groups and scope.
curl https://penv.cloud/api/v1/secrets/DATABASE_URL \
-H "Authorization: Bearer pck_..."{ "value": "postgres://example/not-a-real-secret", "version": 3 }Base URL: https://penv.cloud. Every route answers JSON. We return a read's plaintext value over TLS to the scoped identity that asked.
Callers
| Caller | Example |
|---|---|
| CI platform | Reads values into a build. |
| Pull-based sync tool | Fetches a whole environment on a timer, such as External Secrets Operator. |
| Server script | Reads one value. |
Your application code normally uses penv run or penv pull instead.
Scope
Your credential fixes the workspace, project and environment. The path carries no workspace or environment; we answer an address outside the credential's scope with 404 not_found. Credentials: authentication.
Operation groups
| Group | Covers |
|---|---|
| Secrets | List names, read, write and delete one value, read a whole environment in one call. |
| Dynamic | Mint one short-lived credential from a connected engine; we return it once and store it nowhere. |
| Auth | Exchange a host proof for a pck_ credential; revoke one. |
| Discovery | The two public documents another cloud reads to trust tokens we mint. Unauthenticated. |
Undocumented endpoints
The console, the CLI and our background jobs call further /api/v1 endpoints: workspaces, projects, environments, reveal approvals, billing webhooks, scheduled jobs and SCIM. They are not a public contract, and we change them with the console, without notice or version bump. Stability terms for the documented operations: versioning.
Every error body is {"error": "snake_case_code"}. A 429 from one of our ceilings carries retry-after. Codes: error codes.
Next: authentication.