# Redcee for agents

Canonical agent documentation: https://www.redcee.com/docs/
OpenAPI 3.1 description: https://www.redcee.com/openapi.json
Canonical source: https://www.redcee.com/llms.txt

Redcee stores secrets in a config. An access token selects exactly one config. Prefer the `redcee` CLI; it is a thin client over the same JSON API.

Rules:

1. Never place tokens or secret values in argv, URLs, source, logs, or chat output.
2. Token input: REDCEE_TOKEN, --token-file, or --token-stdin.
3. Mutation value input: --value-file or --value-stdin. There is no --value argument.
4. Before every mutation, run `redcee config show` and pass its decimal-string `config_revision` as --expected-config-revision.
5. On revision_conflict, inspect again; never retry a write blindly.
6. Retry an unknown mutation outcome only with the same UUIDv7 operation ID and exact same input.
7. rc_at_ automation tokens are config-scoped, last 1/7/30 days, and can read/create/replace/history/rollback/restore.
8. rc_st_ service tokens are read-only.
9. No machine endpoint deletes, purges, manages organizations/access, or issues tokens.

CLI grammar:

    redcee config show
    redcee secrets get NAME... [--format plain|json]
    redcee secrets download --format json|env [--out PATH]
    redcee secrets create NAME --value-file PATH|--value-stdin --expected-config-revision REVISION [--type TYPE] [--operation-id UUIDV7]
    redcee secrets replace NAME --value-file PATH|--value-stdin --expected-config-revision REVISION [--type TYPE] [--operation-id UUIDV7]
    redcee secrets versions NAME [--page-size 1..100] [--before-version-number NUMBER]
    redcee secrets rollback NAME VERSION_UUIDV7 --expected-config-revision REVISION [--operation-id UUIDV7]
    redcee secrets restore NAME VERSION_UUIDV7 --expected-config-revision REVISION [--operation-id UUIDV7]
    redcee run [--replace-existing] -- PROGRAM [ARG...]

Production API origin: https://redcee.com
CLI override for explicit alternate deployment: REDCEE_URL

Stable API error envelope:

    {"error":{"code":"revision_conflict","message":"...","request_id":"UUIDV7"}}

Stable codes: invalid_request, validation_error, invalid_token, insufficient_scope, not_found, read_conflict, revision_conflict, idempotency_conflict, lifecycle_conflict, service_unavailable, internal_error.

Canonical API routes:

    GET /api/v1/config
    GET /api/v1/secrets
    GET /api/v1/secrets/{name}
    POST /api/v1/secrets
    PUT /api/v1/secrets/{name}
    GET /api/v1/secrets/{name}/versions
    POST /api/v1/secrets/{name}/versions/{version_id}/rollback
    POST /api/v1/secrets/{name}/versions/{version_id}/restore

Minimal mutation loop:

1. `redcee config show`
2. Capture config_revision.
3. Generate UUIDv7 operation ID.
4. Submit one mutation with value from file/stdin.
5. Transport failure with unknown outcome: retry exact input and same operation ID.
6. revision_conflict: stop, inspect, decide, use a new operation ID.