{
  "openapi": "3.1.0",
  "info": {
    "title": "harness-api",
    "version": "1.0.0",
    "description": "The API behind the 5 Kings Agentic Commerce Harness: a customer submits a task against their provisioned workspace with the key issued at provisioning, and a person confirms it within one business day. Tasks are recorded, not executed on submission — the confirmation is the product.",
    "contact": {
      "name": "5 Kings Marketing",
      "url": "https://www.5kingsmarketing.com/harness-api/",
      "email": "support@5kingsmarketing.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.5kingsmarketing.com/terms/"
    }
  },
  "servers": [
    {
      "url": "https://www.5kingsmarketing.com/wp-json/harness/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "operationId": "getWorkspace",
        "summary": "Workspace summary",
        "description": "The workspace the key belongs to: its identifier, the SKU and product it was provisioned from, its status, when it was provisioned, and how many tasks sit in each status. Use it as the first call an integration makes to prove the key works.",
        "x-upstream": {
          "method": "GET",
          "path": "/wp-json/harness/v1/me"
        },
        "responses": {
          "200": {
            "description": "The workspace bound to the presented key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Workspace"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is not recognised.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key belongs to a request that is not provisioned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Read rate limit exceeded (600 per hour per key).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "Submit a task",
        "description": "Records a task against the workspace. The task is not executed on submission: it is queued, the operator is notified, and a person confirms within one business day. The 201 says received, not started.",
        "x-upstream": {
          "method": "POST",
          "path": "/wp-json/harness/v1/tasks"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskCreate"
              },
              "examples": {
                "defect": {
                  "summary": "A defect with the store URL",
                  "value": {
                    "task": "Collection pages duplicate the product title in the H1. Diagnose and fix, then verify the live output.",
                    "store_url": "https://example-store.com",
                    "platform": "shopify"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Task recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskCreated"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is not recognised.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key belongs to a request that is not provisioned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The task is under 10 or over 8,000 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Submission rate limit exceeded (30 per hour per key).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "listTasks",
        "summary": "List tasks",
        "description": "Your tasks, newest first. Scoped to the key: there is no parameter that reaches another workspace.",
        "x-upstream": {
          "method": "GET",
          "path": "/wp-json/harness/v1/tasks"
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many tasks to return, 1 to 100. Default 20.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The workspace and its tasks.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskList"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is not recognised.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Read rate limit exceeded (600 per hour per key).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tasks/{id}": {
      "get": {
        "operationId": "getTask",
        "summary": "One task",
        "description": "A single task and its status. A task in another workspace returns 404 rather than 403, so the API does not confirm the existence of work the caller cannot see.",
        "x-upstream": {
          "method": "GET",
          "path": "/wp-json/harness/v1/tasks/{id}"
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The task id returned on creation.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The task.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Task"
                }
              }
            }
          },
          "401": {
            "description": "No key, or a key that is not recognised.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No task with that id in this workspace.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ach_<40 hex>",
        "description": "The key issued in the access email: Authorization: Bearer ach_…"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "The same key as a header, for clients or proxies that drop Authorization."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "A machine-readable failure. The code is stable; the message is for a human.",
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "ach_missing_key",
              "ach_invalid_key",
              "ach_key_not_active",
              "ach_task_too_short",
              "ach_task_too_long",
              "ach_rate_limited",
              "ach_task_not_found"
            ]
          },
          "message": {
            "type": "string",
            "maxLength": 400
          },
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "minimum": 100,
                "maximum": 599
              }
            },
            "required": [
              "status"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false
      },
      "Workspace": {
        "type": "object",
        "description": "The workspace bound to the presented key.",
        "properties": {
          "workspace": {
            "type": "string",
            "maxLength": 64,
            "description": "e.g. ws_3aa621170bf5"
          },
          "sku": {
            "type": "string",
            "maxLength": 96,
            "description": "The product SKU, e.g. ACH-WS-BUNDLE"
          },
          "product": {
            "type": "string",
            "maxLength": 300
          },
          "status": {
            "type": "string",
            "enum": [
              "provisioned"
            ],
            "description": "A key only works in this state."
          },
          "provisioned": {
            "type": "string",
            "maxLength": 30,
            "description": "UTC timestamp of provisioning."
          },
          "task_counts": {
            "type": "object",
            "description": "Tasks in each status; absent statuses have no tasks.",
            "properties": {
              "received": {
                "type": "integer",
                "minimum": 0
              },
              "acknowledged": {
                "type": "integer",
                "minimum": 0
              },
              "in_progress": {
                "type": "integer",
                "minimum": 0
              },
              "done": {
                "type": "integer",
                "minimum": 0
              }
            },
            "additionalProperties": false
          },
          "docs": {
            "type": "string",
            "maxLength": 300
          },
          "support": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "workspace",
          "sku",
          "product",
          "status",
          "docs",
          "support"
        ],
        "additionalProperties": false
      },
      "TaskCreate": {
        "type": "object",
        "description": "What you want looked at, and where.",
        "properties": {
          "task": {
            "type": "string",
            "minLength": 10,
            "maxLength": 8000,
            "description": "The defect or query, in enough detail to act on."
          },
          "store_url": {
            "type": "string",
            "maxLength": 255,
            "description": "The store the task concerns."
          },
          "platform": {
            "type": "string",
            "maxLength": 48,
            "description": "shopify, woocommerce, magento, sfcc, bigcommerce, universal…"
          }
        },
        "required": [
          "task"
        ],
        "additionalProperties": false
      },
      "TaskCreated": {
        "type": "object",
        "description": "Receipt for a submitted task.",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "received"
            ]
          },
          "workspace": {
            "type": "string",
            "maxLength": 64
          },
          "message": {
            "type": "string",
            "maxLength": 200
          },
          "next": {
            "type": "string",
            "maxLength": 300
          }
        },
        "required": [
          "id",
          "status",
          "workspace",
          "message"
        ],
        "additionalProperties": false
      },
      "Task": {
        "type": "object",
        "description": "A recorded task and where it has got to.",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "sku": {
            "type": "string",
            "maxLength": 96
          },
          "task": {
            "type": "string",
            "maxLength": 8000
          },
          "store_url": {
            "type": "string",
            "maxLength": 255
          },
          "platform": {
            "type": "string",
            "maxLength": 48
          },
          "status": {
            "type": "string",
            "enum": [
              "received",
              "acknowledged",
              "in_progress",
              "done"
            ],
            "description": "received: recorded, nobody has looked. acknowledged: a person confirmed it. in_progress: being worked. done: delivered."
          },
          "created_at": {
            "type": "string",
            "maxLength": 30
          },
          "updated_at": {
            "type": "string",
            "maxLength": 30
          }
        },
        "required": [
          "id",
          "sku",
          "task",
          "status",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "TaskList": {
        "type": "object",
        "properties": {
          "workspace": {
            "type": "string",
            "maxLength": 64
          },
          "tasks": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/Task"
            }
          }
        },
        "required": [
          "workspace",
          "tasks"
        ],
        "additionalProperties": false
      }
    }
  },
  "tags": [
    {
      "name": "workspace",
      "description": "What the key opens"
    },
    {
      "name": "tasks",
      "description": "Work submitted against the workspace"
    }
  ]
}
