{
  "openapi": "3.1.0",
  "info": {
    "title": "UCP Common Service",
    "description": "Canonical REST interface for UCP Common services, including Location discovery. Schema references are logical pointers - actual payload shape is determined by negotiated capabilities.\n\n**Endpoint Resolution:** This spec defines operations only. The base URL MUST be obtained from the Business's discovery profile at `/.well-known/ucp` under `services[\"dev.ucp.common\"][transport=rest].endpoint`. The `{endpoint}` server variable below is a placeholder for tooling compatibility.",
    "version": "2026-08-25"
  },
  "servers": [
    {
      "url": "{endpoint}",
      "description": "Business-provided endpoint from UCP discovery profile",
      "variables": {
        "endpoint": {
          "default": "https://business.example.com/ucp",
          "description": "Obtain from /.well-known/ucp → services[\"dev.ucp.common\"][transport=rest].endpoint"
        }
      }
    }
  ],
  "paths": {
    "/locations/search": {
      "post": {
        "operationId": "search_locations",
        "summary": "Search Locations",
        "description": "Search for physical locations using query text, explicit spatial relations, and structured filters.",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/location_search_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/location_search_response"
                }
              }
            }
          }
        }
      }
    },
    "/locations/lookup": {
      "post": {
        "operationId": "lookup_locations",
        "summary": "Batch Lookup Locations",
        "description": "Lookup one or more physical Locations by supported identifiers, optionally refined by explicit spatial relations and structured filters.",
        "parameters": [
          {
            "$ref": "#/components/parameters/authorization"
          },
          {
            "$ref": "#/components/parameters/x_api_key"
          },
          {
            "$ref": "#/components/parameters/signature"
          },
          {
            "$ref": "#/components/parameters/signature_input"
          },
          {
            "$ref": "#/components/parameters/content_digest"
          },
          {
            "$ref": "#/components/parameters/request_id"
          },
          {
            "$ref": "#/components/parameters/user_agent"
          },
          {
            "$ref": "#/components/parameters/ucp_agent"
          },
          {
            "$ref": "#/components/parameters/content_type"
          },
          {
            "$ref": "#/components/parameters/accept"
          },
          {
            "$ref": "#/components/parameters/accept_language"
          },
          {
            "$ref": "#/components/parameters/accept_encoding"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/location_lookup_request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lookup results",
            "headers": {
              "Signature": {
                "$ref": "#/components/headers/signature"
              },
              "Signature-Input": {
                "$ref": "#/components/headers/signature_input"
              },
              "Content-Digest": {
                "$ref": "#/components/headers/content_digest"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/location_lookup_response"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "authorization": {
        "name": "Authorization",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Contains an OAuth token representing Platform or Buyer credentials."
      },
      "x_api_key": {
        "name": "X-API-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Reusable API key allocated to the Platform by the Business."
      },
      "signature": {
        "name": "Signature",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 HTTP Message Signature. Format: `sig1=:<base64-signature>:`."
      },
      "signature_input": {
        "name": "Signature-Input",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 Signature-Input header. Format: `sig1=(\"@method\" \"@path\" ...);created=<timestamp>;keyid=\"<key-id>\"`."
      },
      "content_digest": {
        "name": "Content-Digest",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Body digest per RFC 9530. Format: `sha-256=:<base64-digest>:`."
      },
      "request_id": {
        "name": "Request-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Unique UUID for tracing requests across components."
      },
      "user_agent": {
        "name": "User-Agent",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Identifies the user agent string making the call."
      },
      "ucp_agent": {
        "name": "UCP-Agent",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identifies the UCP agent making the call, containing the signer's profile URI. Format: profile=\"https://example.com/.well-known/ucp\"."
      },
      "content_type": {
        "name": "Content-Type",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Representation Metadata describing the body content."
      },
      "accept": {
        "name": "Accept",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Content Negotiation, indicating accepted formats."
      },
      "accept_language": {
        "name": "Accept-Language",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Preferred natural languages for localization."
      },
      "accept_encoding": {
        "name": "Accept-Encoding",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Supported content-codings (compression)."
      }
    },
    "headers": {
      "signature": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 HTTP Message Signature for response."
      },
      "signature_input": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "RFC 9421 Signature-Input header for response."
      },
      "content_digest": {
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Body digest per RFC 9530 for response."
      }
    },
    "schemas": {
      "location_search_request": {
        "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_search.json#/$defs/search_request"
      },
      "location_search_response": {
        "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_search.json#/$defs/search_response"
      },
      "location_lookup_request": {
        "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_lookup.json#/$defs/lookup_request"
      },
      "location_lookup_response": {
        "$ref": "https://ucp.dev/2026-08-25/schemas/common/location_lookup.json#/$defs/lookup_response"
      }
    }
  }
}