{
  "paths": {
    "/contacts": {
      "get": {
        "tags": ["Contacts"],
        "summary": "List contacts",
        "description": "Returns the authenticated user's contacts. Supports search (case-insensitive match on first_name, last_name, email, company) and cursor-based pagination. Requires `contacts:read` scope.",
        "operationId": "listContacts",
        "parameters": [
          { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search term for name, email, or company" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size" },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor" }
        ],
        "responses": {
          "200": {
            "description": "List of contacts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items", "page"],
                  "properties": {
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } },
                    "page": { "$ref": "#/components/schemas/PageInfo" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "post": {
        "tags": ["Contacts"],
        "summary": "Create a contact",
        "description": "Creates a new contact for the authenticated user. At least one identifying field (first_name, last_name, email, or phone) must be provided. Requires `contacts:write` scope.",
        "operationId": "createContact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "first_name": { "type": "string", "example": "Jane" },
                  "last_name": { "type": "string", "example": "Doe" },
                  "email": { "type": "string", "format": "email", "example": "jane@example.com" },
                  "phone": { "type": "string", "example": "+595981000000" },
                  "company": { "type": "string", "example": "Example SA" },
                  "notes": { "type": "string", "example": "Met at event" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["contact"],
                  "properties": {
                    "contact": { "$ref": "#/components/schemas/Contact" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error (e.g. no identifying field)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/contacts/{id}": {
      "get": {
        "tags": ["Contacts"],
        "summary": "Get a contact",
        "description": "Returns a single contact by ID. Only the owner can access their contacts. Requires `contacts:read` scope.",
        "operationId": "getContact",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Contact ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Contact details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["contact"],
                  "properties": {
                    "contact": { "$ref": "#/components/schemas/Contact" }
                  }
                }
              }
            }
          },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "put": {
        "tags": ["Contacts"],
        "summary": "Update a contact",
        "description": "Updates a contact's fields. Only the owner can update their contacts. Requires `contacts:write` scope.",
        "operationId": "updateContact",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Contact ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "first_name": { "type": "string" },
                  "last_name": { "type": "string" },
                  "email": { "type": "string", "format": "email" },
                  "phone": { "type": "string" },
                  "company": { "type": "string" },
                  "notes": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["contact"],
                  "properties": {
                    "contact": { "$ref": "#/components/schemas/Contact" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      },
      "delete": {
        "tags": ["Contacts"],
        "summary": "Delete a contact",
        "description": "Soft-deletes a contact. Only the owner can delete their contacts. Requires `contacts:write` scope.",
        "operationId": "deleteContact",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Contact ID"
          }
        ],
        "responses": {
          "200": { "description": "Contact deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } },
          "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}