POST /api/v1/data/caci-acorn/classify

Classify postcodes using licensed CACI data

Requires exact expected execution mode and connection revision. Live classification consumes licensed records and requires an Idempotency-Key UUID. Review data authority before use.

Authenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.

Delegated agent action: data.postcodes.classify. { requestCount, requestsDigest, expectedExecutionMode, expectedConfigurationRevision }; prepare with { requests: [{ uid, postcode }], expectedExecutionMode, expectedConfigurationRevision }. Consumes licensed CACI records; live execution requires an Idempotency-Key UUID header. Prepare the action, obtain exact human approval, and bind the execution headers. Uncertain provider outcomes require reconciliation, never blind retries.

The request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.

Request

HTTP

POST /api/v1/data/caci-acorn/classify

Use the configured API origin. Private requests require a verified Bearer credential; an agent mutation can additionally require exact approval headers. Authentication guide →

Parameter	Location	Required	Description
`Idempotency-Key`	header	Conditional / optional	Required for live execution; retain the same UUID for the same request after uncertain outcomes.
`x-chorus-agent-step-id`	header	Conditional / optional	Required for a delegated agent mutation: pending execute-step id bound to its approved exact action. Human sessions do not send this header.
`x-chorus-agent-action-digest`	header	Conditional / optional	Required with the agent step id. Use the SHA-256 action digest returned by preparation and approved by a human; do not compute money or alter the action.

Parameter schemas

JSON Schema

[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "required": false,
    "description": "Required for live execution; retain the same UUID for the same request after uncertain outcomes.",
    "schema": {
      "type": "string",
      "format": "uuid"
    }
  },
  {
    "name": "x-chorus-agent-step-id",
    "in": "header",
    "required": false,
    "description": "Required for a delegated agent mutation: pending execute-step id bound to its approved exact action. Human sessions do not send this header.",
    "schema": {
      "type": "string",
      "minLength": 1
    }
  },
  {
    "name": "x-chorus-agent-action-digest",
    "in": "header",
    "required": false,
    "description": "Required with the agent step id. Use the SHA-256 action digest returned by preparation and approved by a human; do not compute money or alter the action.",
    "schema": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  }
]

Request body contract

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "requests": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "uid": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
                },
                "postcode": {
                  "type": "string",
                  "maxLength": 12
                }
              },
              "required": [
                "uid",
                "postcode"
              ],
              "additionalProperties": false
            },
            "maxItems": 50
          },
          "expectedExecutionMode": {
            "type": "string",
            "enum": [
              "sandbox",
              "live"
            ]
          },
          "expectedConfigurationRevision": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "requests",
          "expectedExecutionMode",
          "expectedConfigurationRevision"
        ],
        "additionalProperties": false
      }
    }
  }
}

Responses

Reference schemas resolve through the downloadable OpenAPI components. The specification marks unmodeled success payloads; an unrestricted payload is not a promise that arbitrary fields exist.

400Invalid request or unsupported fields

Response contract

{
  "description": "Invalid request or unsupported fields",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

401Missing or invalid authentication

Response contract

{
  "description": "Missing or invalid authentication",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

403Permission or product scope refused

Response contract

{
  "description": "Permission or product scope refused",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

404Route or tenant-scoped resource not found

Response contract

{
  "description": "Route or tenant-scoped resource not found",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

409State, revision, approval, funding or idempotency conflict

Response contract

{
  "description": "State, revision, approval, funding or idempotency conflict",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

422Supplier configuration, capability or upstream refusal

Response contract

{
  "description": "Supplier configuration, capability or upstream refusal",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

429Rate limit reached; wait before retrying

Response contract

{
  "description": "Rate limit reached; wait before retrying",
  "headers": {
    "x-ratelimit-limit": {
      "description": "Maximum requests permitted in the current rate-limit window.",
      "schema": {
        "type": "integer"
      }
    },
    "x-ratelimit-remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer"
      }
    },
    "x-ratelimit-reset": {
      "description": "Seconds until the current rate-limit window resets.",
      "schema": {
        "type": "integer"
      }
    },
    "retry-after": {
      "description": "Minimum seconds to wait before retrying.",
      "schema": {
        "type": "integer"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

500Internal error; inspect state before retrying a mutation

Response contract

{
  "description": "Internal error; inspect state before retrying a mutation",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

503Dependency or authentication verifier unavailable

Response contract

{
  "description": "Dependency or authentication verifier unavailable",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

2XXSuccessful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.

Response contract

{
  "description": "Successful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.",
  "headers": {
    "x-ratelimit-limit": {
      "description": "Maximum requests permitted in the current rate-limit window.",
      "schema": {
        "type": "integer"
      }
    },
    "x-ratelimit-remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer"
      }
    },
    "x-ratelimit-reset": {
      "description": "Seconds until the current rate-limit window resets.",
      "schema": {
        "type": "integer"
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {}
    }
  }
}

Operation constraints

Machine-readable metadata

{
  "x-response-schema-completeness": "unmodeled",
  "x-rate-limit": {
    "requests": 300,
    "windowMilliseconds": 60000,
    "key": "request IP",
    "headers": [
      "x-ratelimit-limit",
      "x-ratelimit-remaining",
      "x-ratelimit-reset"
    ]
  },
  "x-idempotency": {
    "policy": "live-required",
    "note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
  },
  "x-agent-action": {
    "name": "data.postcodes.classify",
    "budgetPolicy": "zero",
    "parameterContract": "{ requestCount, requestsDigest, expectedExecutionMode, expectedConfigurationRevision }; prepare with { requests: [{ uid, postcode }], expectedExecutionMode, expectedConfigurationRevision }. Consumes licensed CACI records; live execution requires an Idempotency-Key UUID header.",
    "exactApprovalRequired": true
  }
}

Complete operation

OpenAPI

{
  "operationId": "post_api_v1_data_caci_acorn_classify",
  "summary": "Classify postcodes using licensed CACI data",
  "description": "Requires exact expected execution mode and connection revision. Live classification consumes licensed records and requires an Idempotency-Key UUID. Review data authority before use.\n\nAuthenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.\n\nDelegated agent action: data.postcodes.classify. { requestCount, requestsDigest, expectedExecutionMode, expectedConfigurationRevision }; prepare with { requests: [{ uid, postcode }], expectedExecutionMode, expectedConfigurationRevision }. Consumes licensed CACI records; live execution requires an Idempotency-Key UUID header. Prepare the action, obtain exact human approval, and bind the execution headers. Uncertain provider outcomes require reconciliation, never blind retries.\n\nThe request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.",
  "tags": [
    "Data"
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": false,
      "description": "Required for live execution; retain the same UUID for the same request after uncertain outcomes.",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "x-chorus-agent-step-id",
      "in": "header",
      "required": false,
      "description": "Required for a delegated agent mutation: pending execute-step id bound to its approved exact action. Human sessions do not send this header.",
      "schema": {
        "type": "string",
        "minLength": 1
      }
    },
    {
      "name": "x-chorus-agent-action-digest",
      "in": "header",
      "required": false,
      "description": "Required with the agent step id. Use the SHA-256 action digest returned by preparation and approved by a human; do not compute money or alter the action.",
      "schema": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "requests": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "uid": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
                  },
                  "postcode": {
                    "type": "string",
                    "maxLength": 12
                  }
                },
                "required": [
                  "uid",
                  "postcode"
                ],
                "additionalProperties": false
              },
              "maxItems": 50
            },
            "expectedExecutionMode": {
              "type": "string",
              "enum": [
                "sandbox",
                "live"
              ]
            },
            "expectedConfigurationRevision": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": -9007199254740991,
                  "maximum": 9007199254740991
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "requests",
            "expectedExecutionMode",
            "expectedConfigurationRevision"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "400": {
      "description": "Invalid request or unsupported fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Permission or product scope refused",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Route or tenant-scoped resource not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "State, revision, approval, funding or idempotency conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Supplier configuration, capability or upstream refusal",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Rate limit reached; wait before retrying",
      "headers": {
        "x-ratelimit-limit": {
          "description": "Maximum requests permitted in the current rate-limit window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-remaining": {
          "description": "Requests remaining in the current window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-reset": {
          "description": "Seconds until the current rate-limit window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "retry-after": {
          "description": "Minimum seconds to wait before retrying.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error; inspect state before retrying a mutation",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Dependency or authentication verifier unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "2XX": {
      "description": "Successful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.",
      "headers": {
        "x-ratelimit-limit": {
          "description": "Maximum requests permitted in the current rate-limit window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-remaining": {
          "description": "Requests remaining in the current window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-reset": {
          "description": "Seconds until the current rate-limit window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  },
  "x-response-schema-completeness": "unmodeled",
  "x-rate-limit": {
    "requests": 300,
    "windowMilliseconds": 60000,
    "key": "request IP",
    "headers": [
      "x-ratelimit-limit",
      "x-ratelimit-remaining",
      "x-ratelimit-reset"
    ]
  },
  "x-idempotency": {
    "policy": "live-required",
    "note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
  },
  "x-agent-action": {
    "name": "data.postcodes.classify",
    "budgetPolicy": "zero",
    "parameterContract": "{ requestCount, requestsDigest, expectedExecutionMode, expectedConfigurationRevision }; prepare with { requests: [{ uid, postcode }], expectedExecutionMode, expectedConfigurationRevision }. Consumes licensed CACI records; live execution requires an Idempotency-Key UUID header.",
    "exactApprovalRequired": true
  }
}

Download the complete specification, including shared schema components →