{
  "openapi": "3.1.0",
  "info": {
    "title": "get1pct API",
    "version": "1.0.0",
    "description": "Read daily proposals and record how an approved change was handled by your site's integration. The API never writes to the target site or publishes content.\n\n- Plans: works only while the workspace is on an active Growth or Pro plan. Otherwise every call returns 403 forbidden with reason plan_inactive.\n- Rate limit: 60 requests per minute per key. The count restarts 60 seconds after the first request in the window. A 429 response carries Retry-After (seconds).\n- Ownership: POST and PUT on an application read the project's home page each time and require the <meta name=\"get1pct-verification\" ...> line in its head. On Pro, every added site needs its own line on its own home page. Reading projects and proposals does not.\n- application_conflict (409): the change was already handled another way (applied, being applied, failed or reverted by a direct connection, or marked done by the owner), the project has a direct connection (WordPress or a CMS) that applies changes itself, the report's id is not the claimed application id, the site's host changed, or a report contradicts the result already recorded."
  },
  "servers": [{ "url": "https://get1pct.com", "description": "Production" }],
  "security": [{ "workspaceKey": [] }],
  "paths": {
    "/api/v1/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "List projects in the Growth or Pro workspace",
        "responses": {
          "200": {
            "description": "Accessible projects",
            "content": { "application/json": { "schema": {
              "type": "object", "required": ["projects"],
              "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } }
            } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/projects/{id}/proposals": {
      "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
      "get": {
        "operationId": "listProposals",
        "summary": "List up to 50 recent daily proposals",
        "responses": {
          "200": {
            "description": "Recent proposals and application status",
            "content": { "application/json": { "schema": {
              "type": "object", "required": ["proposals"],
              "properties": { "proposals": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/Proposal" } } }
            } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/v1/projects/{id}/proposals/{proposalId}/application": {
      "parameters": [{ "$ref": "#/components/parameters/ProjectId" }, { "$ref": "#/components/parameters/ProposalId" }],
      "post": {
        "operationId": "claimApplication",
        "summary": "Get an approved change and its stable application ID",
        "description": "Requires an application-enabled key and live site ownership proof. Retrying returns the same application. Use the ID as a durable idempotency key in the site's draft store. If the application already has a result, do not apply it again.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["operation"], "additionalProperties": false,
            "properties": { "operation": { "const": "save_draft" } }
          } } }
        },
        "responses": {
          "200": {
            "description": "Application and approved change",
            "content": { "application/json": { "schema": {
              "type": "object", "required": ["application", "change"],
              "properties": { "application": { "$ref": "#/components/schemas/Application" }, "change": { "$ref": "#/components/schemas/Change" } }
            } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      },
      "put": {
        "operationId": "reportApplication",
        "summary": "Report a draft, a failure, or publication that already happened",
        "description": "Requires an application-enabled key and live site ownership proof. Replaying an identical report is safe. A publication report must reference the previously reported draft revision and does not publish anything.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } },
        "responses": {
          "200": {
            "description": "Report accepted, including reports of a failed write",
            "content": { "application/json": { "schema": {
              "type": "object", "required": ["application"],
              "properties": { "application": { "$ref": "#/components/schemas/Application" } }
            } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "409": { "$ref": "#/components/responses/Error" },
          "422": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "workspaceKey": { "type": "http", "scheme": "bearer", "bearerFormat": "opct_ workspace key" }
    },
    "parameters": {
      "ProjectId": { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Id" } },
      "ProposalId": { "name": "proposalId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Id" } }
    },
    "responses": {
      "Error": {
        "description": "The request did not succeed. Check the HTTP status and error.code.",
        "content": { "application/json": { "schema": {
          "type": "object", "required": ["error"],
          "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }
        } } }
      },
      "RateLimited": {
        "description": "More than 60 requests in a minute with this key. Wait for Retry-After seconds before retrying.",
        "headers": { "Retry-After": { "description": "Seconds until the count restarts", "schema": { "type": "integer", "minimum": 1 } } },
        "content": { "application/json": { "schema": {
          "type": "object", "required": ["error"],
          "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }
        } } }
      }
    },
    "schemas": {
      "ErrorBody": {
        "type": "object", "required": ["code"],
        "properties": {
          "code": { "enum": ["invalid_request", "unauthorized", "forbidden", "ownership_required", "not_found", "not_approved", "application_conflict", "unsupported_change", "unsupported_operation", "rate_limited", "unavailable"] },
          "reason": { "enum": ["plan_inactive", "applications_disabled", "daily_paused"], "description": "Present only with forbidden. plan_inactive: the plan is not an active Growth or Pro plan. applications_disabled: POST or PUT with a key that was not created to record results. daily_paused: daily proposals are paused for the project (only POST is refused; results of an application already claimed can still be reported with PUT)." }
        }
      },
      "Id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" },
      "Field": { "enum": ["title", "description", "h1", "body"] },
      "Revision": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{1,128}$", "description": "Opaque revision identifier without secrets." },
      "FailureCode": { "enum": ["unsupported", "conflict", "rejected"] },
      "Timestamp": { "type": "integer", "description": "Unix timestamp in milliseconds" },
      "Project": {
        "type": "object", "required": ["id", "host", "url"],
        "properties": { "id": { "$ref": "#/components/schemas/Id" }, "host": { "type": "string" }, "url": { "type": "string", "format": "uri" } }
      },
      "Proposal": {
        "type": "object", "required": ["id", "date", "page", "field", "before", "after", "reason", "status", "applicationStatus"],
        "properties": {
          "id": { "$ref": "#/components/schemas/Id" },
          "date": { "type": "string", "format": "date" },
          "page": { "type": "string", "format": "uri" },
          "field": { "$ref": "#/components/schemas/Field" },
          "before": { "type": "string" },
          "after": { "type": "string" },
          "reason": { "type": "string" },
          "status": { "enum": ["shown", "approved", "edited", "rejected"] },
          "applicationStatus": { "enum": ["none", "applying", "applied", "copy", "failed", "reverted", "claimed", "draft_saved", "published"] }
        }
      },
      "Change": {
        "type": "object", "required": ["operation", "page", "field", "before", "after"],
        "properties": {
          "operation": { "const": "save_draft" },
          "page": { "type": "string", "format": "uri" },
          "field": { "$ref": "#/components/schemas/Field" },
          "before": { "type": "string" },
          "after": { "type": "string" }
        }
      },
      "Application": {
        "type": "object", "required": ["id", "claimedAt", "result", "published"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "claimedAt": { "$ref": "#/components/schemas/Timestamp" },
          "result": { "oneOf": [
            { "type": "null" },
            { "type": "object", "required": ["status", "revision", "at"], "properties": { "status": { "const": "draft_saved" }, "revision": { "$ref": "#/components/schemas/Revision" }, "at": { "$ref": "#/components/schemas/Timestamp" } } },
            { "type": "object", "required": ["status", "code", "at"], "properties": { "status": { "const": "failed" }, "code": { "$ref": "#/components/schemas/FailureCode" }, "at": { "$ref": "#/components/schemas/Timestamp" } } }
          ] },
          "published": { "oneOf": [
            { "type": "null" },
            { "type": "object", "required": ["status", "draftRevision", "revision", "at"], "properties": { "status": { "const": "published" }, "draftRevision": { "$ref": "#/components/schemas/Revision" }, "revision": { "$ref": "#/components/schemas/Revision" }, "at": { "$ref": "#/components/schemas/Timestamp" } } }
          ] }
        }
      },
      "Report": {
        "oneOf": [
          { "type": "object", "additionalProperties": false, "required": ["id", "status", "revision"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "draft_saved" }, "revision": { "$ref": "#/components/schemas/Revision" } } },
          { "type": "object", "additionalProperties": false, "required": ["id", "status", "code"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "failed" }, "code": { "$ref": "#/components/schemas/FailureCode" } } },
          { "type": "object", "additionalProperties": false, "required": ["id", "status", "draftRevision", "revision"], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "published" }, "draftRevision": { "$ref": "#/components/schemas/Revision" }, "revision": { "$ref": "#/components/schemas/Revision" } } }
        ]
      }
    }
  }
}
