{
  "openapi": "3.1.0",
  "info": {
    "title": "Threadkeep Agent Checkpoints",
    "version": "1.0.0",
    "description": "Durable task state for context resets and agent handoffs. No AI call, purchase, or external action occurs. Free: 3 tasks and 100 checkpoint writes/month. Pro: $12/month, 100 tasks and 10,000 writes/month. State is a full replacement; use optimistic versions and retry the same request_id with identical data.",
    "termsOfService": "https://interesting-concepts-ventures.vercel.app/threadkeep/terms"
  },
  "servers": [
    {
      "url": "https://interesting-concepts-ventures.vercel.app"
    }
  ],
  "externalDocs": {
    "url": "https://interesting-concepts-ventures.vercel.app/threadkeep/agents/guide.md"
  },
  "components": {
    "securitySchemes": {
      "agentKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Threadkeep-Agent-Key"
      }
    }
  },
  "paths": {
    "/api/threadkeep-agent": {
      "post": {
        "operationId": "threadkeepAgent",
        "summary": "Register, checkpoint, resume or list agent tasks",
        "description": "register requires no header: generate and persist owner_key and agent_key before calling, and accept terms only when authorized. All other actions require X-Threadkeep-Agent-Key. task_id is workspace-scoped. Checkpoint state max 24,000 UTF-8 bytes stored. Read actions do not use write allowance. A key may be limited to one task. 60 requests/minute/workspace. request_id deduplicated for 90 days; version checks always prevent overwriting newer state.",
        "security": [
          {
            "agentKey": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "type": "object",
                    "properties": {
                      "owner_key": {
                        "type": "string",
                        "pattern": "^tk_[a-f0-9]{64}$"
                      },
                      "agent_key": {
                        "type": "string",
                        "pattern": "^ta_[a-f0-9]{64}$"
                      },
                      "accept_terms": {
                        "type": "boolean",
                        "const": true
                      },
                      "label": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 80
                      },
                      "task_scope": {
                        "type": "string",
                        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$"
                      },
                      "action": {
                        "type": "string",
                        "const": "register"
                      }
                    },
                    "required": [
                      "owner_key",
                      "agent_key",
                      "accept_terms",
                      "action"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "type": "object",
                    "properties": {
                      "action": {
                        "type": "string",
                        "const": "list"
                      }
                    },
                    "required": [
                      "action"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "type": "object",
                    "properties": {
                      "task_id": {
                        "type": "string",
                        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$"
                      },
                      "action": {
                        "type": "string",
                        "const": "read"
                      }
                    },
                    "required": [
                      "task_id",
                      "action"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",
                    "type": "object",
                    "properties": {
                      "task_id": {
                        "type": "string",
                        "pattern": "^[a-z0-9][a-z0-9_-]{0,79}$"
                      },
                      "expected_version": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 2147483646
                      },
                      "request_id": {
                        "type": "string",
                        "format": "uuid",
                        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                      },
                      "state": {
                        "type": "object",
                        "properties": {
                          "goal": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 2000
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "working",
                              "blocked",
                              "done"
                            ]
                          },
                          "completed": {
                            "default": [],
                            "maxItems": 40,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 1200
                            }
                          },
                          "decisions": {
                            "default": [],
                            "maxItems": 40,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 1200
                            }
                          },
                          "constraints": {
                            "default": [],
                            "maxItems": 40,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 1200
                            }
                          },
                          "next_actions": {
                            "maxItems": 40,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 1200
                            }
                          },
                          "blockers": {
                            "default": [],
                            "maxItems": 40,
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 1200
                            }
                          },
                          "artifacts": {
                            "default": [],
                            "maxItems": 30,
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "uri": {
                                  "type": "string",
                                  "maxLength": 2000
                                },
                                "description": {
                                  "type": "string",
                                  "maxLength": 500
                                }
                              },
                              "required": [
                                "uri",
                                "description"
                              ],
                              "additionalProperties": false
                            }
                          }
                        },
                        "required": [
                          "goal",
                          "status",
                          "completed",
                          "decisions",
                          "constraints",
                          "next_actions",
                          "blockers",
                          "artifacts"
                        ],
                        "additionalProperties": false
                      },
                      "action": {
                        "type": "string",
                        "const": "checkpoint"
                      }
                    },
                    "required": [
                      "task_id",
                      "expected_version",
                      "request_id",
                      "state",
                      "action"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Registration: workspace_id, token_id, plan, task_scope. Checkpoint: task_id, version, saved_at, replayed. Read: task {task_id, state, version, updated_at}. List: tasks[], plan, writes_used, writes_limit, task_limit.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing, invalid or revoked agent key"
          },
          "402": {
            "description": "Plan allowance exhausted; owner upgrade required"
          },
          "403": {
            "description": "Origin rejected or key scoped to another task"
          },
          "404": {
            "description": "Task does not exist"
          },
          "409": {
            "description": "version_conflict with current_version: read and reconcile before a new request. idempotency_conflict: same request_id used with different data."
          },
          "413": {
            "description": "Payload too large"
          },
          "429": {
            "description": "Rate or beta capacity limit; back off according to error window"
          },
          "503": {
            "description": "Retry same request_id and payload"
          }
        }
      }
    }
  }
}