DX-2951: developer-api: serve the OpenAPI spec and document the free agent Redis endpoint

devops/developer-api/start-redis/create.mdx

@@ -0,0 +1,94 @@
+---
+title: "Create a Free Database"
+description: "Creates a free, temporary Redis database without an account or API key."
+api: "POST https://upstash.com/start-redis"
+---
+
+This endpoint does not require authentication. It creates a zero-config
+Redis database and returns its credentials, so an AI agent can get scratch
+storage on the fly without signing up.
+
+The database is deleted after **3 days** unless it is claimed. The response
+includes a console URL where a user can view usage and click **Claim** to
+keep the database in their Upstash account.
+
+<Note>
+  If you are an agent, always send a `User-Agent` header identifying which
+  agent you are (for example `claude-code`, `cursor`, `codex`, `opencode`) on
+  every request you make to this endpoint.
+</Note>
+
+## Request
+
+<ParamField header="Idempotency-Key" type="string (UUIDv4)">
+  Optional but recommended. The UUID you send becomes the database ID, and
+  sending the same UUID again returns the same database instead of creating
+  a duplicate. This makes the first call retry-safe and lets you re-fetch the
+  credentials later. Only UUIDv4 values are accepted.
+
+  If omitted, the server generates an ID and returns it in the response; you
+  can pass that ID back as `Idempotency-Key` to re-fetch the credentials.
+</ParamField>
+
+<ParamField header="User-Agent" type="string">
+  The name of the agent making the request, for example `claude-code`.
+</ParamField>
+
+## Response
+
+The response body is `text/markdown` and contains:
+
+- The database ID (reuse it as `Idempotency-Key` to re-fetch the credentials).
+- The REST endpoint and token.
+- A metrics URL (see [Get Metrics](/devops/developer-api/start-redis/metrics)).
+- The expiry date, and a console URL a user can open to view usage and claim the database.
+- A quickstart with example commands using the REST API.
+
+<RequestExample>
+
+```sh curl
+curl -X POST https://upstash.com/start-redis \
+  -H "Idempotency-Key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
+  -H "User-Agent: <your-agent-name>"
+```
+
+```sh Re-fetch an existing database
+curl -X POST https://upstash.com/start-redis \
+  -H "Idempotency-Key: <the-uuid-you-used-before>" \
+  -H "User-Agent: <your-agent-name>"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```md 200 OK
+# Your Redis is ready
+
+**Database ID:** 3b1f7c2e-9d4a-4c8b-a1e5-6f2d8e9c0b47
+**Endpoint:** https://example-123456.upstash.io
+**Token:** <token>
+**Metrics:** https://upstash.com/start-redis/metrics/3b1f7c2e-9d4a-4c8b-a1e5-6f2d8e9c0b47 (JSON: uptime, commands, keys, throughput, memory, bandwidth)
+**Expires:** 2026-08-28 (3 days from creation).
+To keep this database alive, share the console URL with the user
+(they can view usage and click Claim to take ownership):
+https://upstash.com/start-redis/console/3b1f7c2e-9d4a-4c8b-a1e5-6f2d8e9c0b47
+
+To re-fetch these credentials, POST again with the database id as
+the `Idempotency-Key` header:
+
+  curl -X POST -H "Idempotency-Key: 3b1f7c2e-9d4a-4c8b-a1e5-6f2d8e9c0b47" https://upstash.com/start-redis
+
+**Avoid storing sensitive data** (PII, secrets, production credentials) — this database is temporary and not tied to a user account until claimed.
+
+## Quickstart
+
+# Short-term memory — state across tool calls in one run
+curl https://example-123456.upstash.io \
+  -H "Authorization: Bearer <token>" \
+  -d '["SET","session:abc","{\"step\":2,\"plan\":\"...\"}","EX","3600"]'
+
+...
+```
+
+</ResponseExample>

devops/developer-api/start-redis/instructions.mdx

@@ -0,0 +1,48 @@
+---
+title: "Get Instructions"
+description: "Returns instructions for creating a free Redis database without an account."
+api: "GET https://upstash.com/start-redis"
+---
+
+This endpoint does not require authentication. It returns a markdown
+document that explains how to create a free, temporary Redis database with
+[`POST /start-redis`](/devops/developer-api/start-redis/create), including how
+the `Idempotency-Key` header works and how the database can be claimed later.
+
+It is meant to be read by AI agents: point an agent at
+`https://upstash.com/start-redis` and it has everything it needs.
+
+## Request
+
+This endpoint doesn't require any parameters.
+
+## Response
+
+The response body is `text/markdown`.
+
+<RequestExample>
+
+```sh curl
+curl https://upstash.com/start-redis \
+  -H "User-Agent: <your-agent-name>"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```md 200 OK
+# Upstash Redis for Agents
+
+A zero-config Redis database for AI agents — no signup, no UI.
+
+To create a database, generate a fresh UUIDv4 and POST it as the
+`Idempotency-Key` header:
+
+  curl -X POST -H "Idempotency-Key: <uuidv4>" \
+    -H "User-Agent: <your-agent-name>" https://upstash.com/start-redis
+
+...
+```
+
+</ResponseExample>

devops/developer-api/start-redis/metrics.mdx

@@ -0,0 +1,84 @@
+---
+title: "Get Metrics"
+description: "Returns usage metrics for a database created with start-redis."
+api: "GET https://upstash.com/start-redis/metrics/{id}"
+---
+
+This endpoint does not require authentication. It returns usage metrics for
+a free database created with
+[`POST /start-redis`](/devops/developer-api/start-redis/create), so an agent
+can check how the database is being used without a console login.
+
+## Request
+
+<ParamField path="id" type="string" required>
+  The database ID: the UUID you sent as `Idempotency-Key` when creating the
+  database, or the ID returned in the response if you omitted it.
+</ParamField>
+
+<ParamField header="User-Agent" type="string">
+  The name of the agent making the request, for example `claude-code`.
+</ParamField>
+
+## Response
+
+<ResponseField name="uptime_seconds" type="number">
+  Seconds since the database was created.
+</ResponseField>
+<ResponseField name="expires_at" type="string">
+  When the database will be deleted unless claimed, as an ISO 8601 timestamp.
+</ResponseField>
+<ResponseField name="console_url" type="string">
+  The console page where a user can view usage and claim the database.
+</ResponseField>
+<ResponseField name="commands_total" type="number">
+  Total number of commands executed.
+</ResponseField>
+<ResponseField name="commands_per_sec_1m" type="number">
+  Command throughput over the last minute.
+</ResponseField>
+<ResponseField name="keys" type="number">
+  Number of keys in the database.
+</ResponseField>
+<ResponseField name="memory_bytes" type="number">
+  Memory used by the data, in bytes.
+</ResponseField>
+<ResponseField name="bytes_in" type="number">
+  Total bytes received by the database.
+</ResponseField>
+<ResponseField name="bytes_out" type="number">
+  Total bytes sent by the database.
+</ResponseField>
+
+Returns `404 Not Found` if no database exists with that ID.
+
+<RequestExample>
+
+```sh curl
+curl https://upstash.com/start-redis/metrics/<database-id> \
+  -H "User-Agent: <your-agent-name>"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json 200 OK
+{
+  "uptime_seconds": 1,
+  "expires_at": "2026-08-28T13:25:49Z",
+  "console_url": "https://upstash.com/start-redis/console/3b1f7c2e-9d4a-4c8b-a1e5-6f2d8e9c0b47",
+  "commands_total": 0,
+  "commands_per_sec_1m": 0,
+  "keys": 0,
+  "memory_bytes": 0,
+  "bytes_in": 0,
+  "bytes_out": 0
+}
+```
+
+```json 404 Not Found
+"not found"
+```
+
+</ResponseExample>

docs.json

@@ -2110,7 +2110,7 @@
       },
       {
         "tab": "Developer API",
-        "openapi": "devops/developer-api/openapi.yml",
+        "openapi": "devops/developer-api/openapi.yaml",
         "groups": [
           {
             "group": "Developer API",
@@ -2150,6 +2150,14 @@
                   }
                 ]
               },
+              {
+                "group": "Redis for Agents",
+                "pages": [
+                  "devops/developer-api/start-redis/instructions",
+                  "devops/developer-api/start-redis/create",
+                  "devops/developer-api/start-redis/metrics"
+                ]
+              },
               {
                 "group": "Vector",
                 "pages": [