{
  "openapi": "3.1.0",
  "info": {
    "title": "Clockrook API",
    "version": "0.1.0",
    "description": "Scheduled jobs for AI agents. One account works on every agent-first site run by API Evangelist.",
    "contact": {
      "email": "info@apievangelist.com"
    },
    "license": {
      "name": "Apache-2.0"
    }
  },
  "servers": [
    {
      "url": "https://clockrook.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from POST /v1/accounts (shown once)."
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/v1/jobs": {
      "post": {
        "operationId": "create_job",
        "summary": "Schedule a job",
        "description": "Run something later or repeatedly. kind ping delivers your payload (a reminder or callback); uptime checks check_url and alerts after alert_after failures; watch fetches check_url and delivers a diff when it changes. schedule is one of {at}, {every_seconds} or {cron (5-field), timezone}. target is {url} (signed POST, secret shown once), {inbox_id} (a Hookpie inbox) or {email: true}.",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "A label"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "ping",
                      "uptime",
                      "watch"
                    ]
                  },
                  "schedule": {
                    "type": "object"
                  },
                  "target": {
                    "type": "object"
                  },
                  "payload": {
                    "description": "JSON delivered with a ping"
                  },
                  "check_url": {
                    "type": "string",
                    "description": "URL for uptime or watch"
                  },
                  "alert_after": {
                    "type": "integer",
                    "description": "Uptime failures before alerting (default 3)"
                  },
                  "json_path": {
                    "type": "string",
                    "description": "Watch only part of a JSON response, e.g. $.data.price"
                  }
                },
                "required": [
                  "schedule",
                  "target"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "get": {
        "operationId": "list_jobs",
        "summary": "List jobs",
        "description": "Your jobs, their schedules and last run.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "operationId": "get_job",
        "summary": "One job",
        "description": "A job and its state.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "delete": {
        "operationId": "delete_job",
        "summary": "Delete a job",
        "description": "Remove the job and its schedule.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/jobs/{id}/run": {
      "post": {
        "operationId": "run_job",
        "summary": "Run a job now",
        "description": "Run it immediately, outside its schedule (metered like any run).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/jobs/{id}/runs": {
      "get": {
        "operationId": "list_runs",
        "summary": "Run history",
        "description": "Recent runs: outcome, status, latency, delivery.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "description": "1-100"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/jobs/{id}/pause": {
      "post": {
        "operationId": "pause_job",
        "summary": "Pause a job",
        "description": "Stop it running until resumed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/jobs/{id}/resume": {
      "post": {
        "operationId": "resume_job",
        "summary": "Resume a job",
        "description": "Start a paused job again.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/accounts": {
      "post": {
        "operationId": "create_account",
        "summary": "Create an account",
        "description": "Create an account (one account and one prepaid balance work on every agent-first site: Yawplet, Yarnhen, Hagglebee, Eventwren, Hookpie, Clockrook, Rainplover). accept_terms must be true only when the human owner accepts them. Returns an API key once; give account_url to the owner to verify their email.",
        "security": [],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Account owner name"
                  },
                  "email": {
                    "type": "string",
                    "description": "Owner email"
                  },
                  "handle": {
                    "type": "string",
                    "description": "Optional public handle"
                  },
                  "accept_terms": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name",
                  "email",
                  "accept_terms"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "operationId": "get_account",
        "summary": "Account balance and standing",
        "description": "Balance (micro-dollars), whether email is verified and a card or wallet is on file, and a fresh account_url for the owner.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "get_usage",
        "summary": "This period's usage",
        "description": "Metered use this month (or day), the free allowance and the unit price.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/pricing": {
      "get": {
        "operationId": "get_pricing",
        "summary": "Prices",
        "description": "Free allowances and per-unit prices in micro-dollars (1 USD = 1,000,000).",
        "security": [],
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid (problem details)"
          },
          "401": {
            "description": "API key required"
          },
          "402": {
            "description": "The owner must act: see account_url"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    }
  }
}
