{
  "entries": [
    {
      "match": {
        "method": "get",
        "path": "/api/v1/clients"
      },
      "metadata": {
        "displayName": "List Clients",
        "summary": "Fetch clients for the current tenant",
        "description": "Returns paginated client records. Use this before creating tickets to map human-readable client names to client_id values.",
        "parameters": [
          {
            "name": "client_name",
            "in": "query",
            "required": false,
            "description": "Optional case-insensitive filter on the client name.",
            "schema": { "type": "string" }
          },
          {
            "name": "is_inactive",
            "in": "query",
            "required": false,
            "description": "When true, include inactive clients as well as active ones.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of records per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number starting at 1.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "Find a specific client",
            "request": {
              "query": {
                "client_name": "Acme",
                "limit": 5
              }
            },
            "notes": "Use a small limit when searching for a client name mentioned by the user so you can quickly grab the matching client_id. If the user did not name a specific client, reuse the first client_id returned."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/contacts"
      },
      "metadata": {
        "displayName": "List Contacts",
        "summary": "Fetch contacts",
        "description": "Paginated list of contacts. Filter by client_id to retrieve contacts for a specific client when preparing a ticket.",
        "parameters": [
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Restrict contacts to a specific client.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "search_term",
            "in": "query",
            "required": false,
            "description": "Search text to match against contact names or emails.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of records per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "Find client contacts",
            "request": {
              "query": {
                "client_id": "22222222-2222-2222-2222-222222222222",
                "limit": 5
              }
            },
            "notes": "Use the client_id discovered from the clients endpoint to retrieve matching contacts and resolve contact_name_id."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/clients/{id}/locations"
      },
      "metadata": {
        "displayName": "List Client Locations",
        "summary": "Fetch locations for a client",
        "description": "Returns the saved locations for the specified client. Call this when a ticket needs a location_id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Client identifier whose locations should be listed.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of locations to return (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "List locations for client",
            "request": {
              "params": { "id": "22222222-2222-2222-2222-222222222222" },
              "query": { "limit": 5 }
            },
            "notes": "Use the same client_id supplied to the ticket create payload."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/boards"
      },
      "metadata": {
        "displayName": "List Boards",
        "summary": "Fetch ticket boards",
        "description": "Returns paginated board records for the current tenant. Use this to discover valid board_id values before creating tickets or statuses. Each board has its own set of statuses, categories, and priorities.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search on board name or description.",
            "schema": { "type": "string" }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "required": false,
            "description": "When true, include inactive boards (excluded by default).",
            "schema": { "type": "boolean" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of records per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number starting at 1.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "List active boards",
            "request": {
              "query": {
                "limit": 10
              }
            },
            "notes": "Use the board_id from the response when creating tickets or querying statuses. The first active board is a safe default if the user does not specify a board."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/boards/{id}"
      },
      "metadata": {
        "displayName": "Get Board",
        "summary": "Get board by ID",
        "description": "Returns a single board record by its UUID.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Board identifier.",
            "schema": { "type": "string", "format": "uuid" }
          }
        ]
      }
    },
    {
      "match": {
        "method": "post",
        "path": "/api/v1/boards"
      },
      "metadata": {
        "displayName": "Create Board",
        "summary": "Create a new ticket board",
        "description": "Creates a new board. After creating a board, create at least one status for it via POST /api/v1/statuses so tickets can be assigned to the board.",
        "approvalRequired": true,
        "requestBodySchema": {
          "type": "object",
          "properties": {
            "board_name": { "type": "string", "description": "Board display name." },
            "description": { "type": "string", "description": "Optional board description." },
            "is_default": { "type": "boolean", "description": "Whether this is the default board." },
            "is_inactive": { "type": "boolean", "description": "Whether the board is inactive." },
            "category_type": { "type": "string", "enum": ["custom", "itil"], "description": "Category classification type." },
            "priority_type": { "type": "string", "enum": ["custom", "itil"], "description": "Priority classification type." }
          },
          "required": ["board_name"]
        },
        "examples": [
          {
            "name": "Create a new board",
            "request": {
              "body": {
                "board_name": "Support",
                "description": "General support board"
              }
            },
            "notes": "After creating, add statuses via POST /api/v1/statuses with the new board_id and status_type 'ticket'."
          }
        ]
      }
    },
    {
      "match": {
        "method": "put",
        "path": "/api/v1/boards/{id}"
      },
      "metadata": {
        "displayName": "Update Board",
        "summary": "Update a board",
        "description": "Updates an existing board. All fields are optional — only send the fields you want to change.",
        "approvalRequired": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Board identifier.",
            "schema": { "type": "string", "format": "uuid" }
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/statuses"
      },
      "metadata": {
        "displayName": "List Statuses",
        "summary": "Fetch statuses",
        "description": "Returns paginated status records. For ticket statuses, always filter by board_id to get statuses that belong to a specific board. Use this to resolve a valid status_id before creating or updating tickets.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by status type: ticket, project, project_task, or interaction.",
            "schema": { "type": "string", "enum": ["ticket", "project", "project_task", "interaction"] }
          },
          {
            "name": "board_id",
            "in": "query",
            "required": false,
            "description": "Required when type=ticket. Filter statuses belonging to a specific board.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Case-insensitive search on status name.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of records per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number starting at 1.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "List ticket statuses for a board",
            "request": {
              "query": {
                "type": "ticket",
                "board_id": "11111111-1111-1111-1111-111111111111",
                "limit": 25
              }
            },
            "notes": "Always pair type=ticket with board_id. Use the status_id from results when creating tickets — the status_id must belong to the same board_id used on the ticket."
          }
        ]
      }
    },
    {
      "match": {
        "method": "post",
        "path": "/api/v1/statuses"
      },
      "metadata": {
        "displayName": "Create Status",
        "summary": "Create a new status",
        "description": "Creates a new status. For ticket statuses, board_id is required. The status_type must be one of: ticket, project, project_task, interaction.",
        "approvalRequired": true,
        "requestBodySchema": {
          "type": "object",
          "properties": {
            "name": { "type": "string", "description": "Status display name." },
            "status_type": { "type": "string", "enum": ["ticket", "project", "project_task", "interaction"], "description": "Type of entity this status applies to." },
            "board_id": { "type": "string", "format": "uuid", "description": "Required for ticket statuses. The board this status belongs to." },
            "is_closed": { "type": "boolean", "description": "Whether this status represents a closed state." },
            "is_default": { "type": "boolean", "description": "Whether this is the default status for the board." },
            "order_number": { "type": "integer", "description": "Display order position." },
            "color": { "type": "string", "description": "Hex color code (e.g. #3B82F6)." },
            "icon": { "type": "string", "description": "Lucide icon name (e.g. Clipboard, PlayCircle)." }
          },
          "required": ["name", "status_type"]
        },
        "examples": [
          {
            "name": "Create a ticket status for a board",
            "request": {
              "body": {
                "name": "In Progress",
                "status_type": "ticket",
                "board_id": "11111111-1111-1111-1111-111111111111",
                "is_closed": false,
                "color": "#3B82F6"
              }
            },
            "notes": "Use GET /api/v1/boards first to resolve the board_id. The board_id is required for ticket statuses."
          }
        ]
      }
    },
    {
      "match": {
        "method": "put",
        "path": "/api/v1/statuses/{id}"
      },
      "metadata": {
        "displayName": "Update Status",
        "summary": "Update a status",
        "description": "Updates an existing status. All fields are optional — only send the fields you want to change. Cannot change status_type or board_id after creation.",
        "approvalRequired": true,
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Status identifier.",
            "schema": { "type": "string", "format": "uuid" }
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/categories/ticket"
      },
      "metadata": {
        "displayName": "List Ticket Categories",
        "summary": "Fetch ticket categories",
        "description": "Provides the category catalog used when assigning category_id or subcategory_id to a ticket.",
        "parameters": [
          {
            "name": "board_id",
            "in": "query",
            "required": false,
            "description": "Filter categories that belong to a specific ticket board.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "description": "Toggle to include inactive categories.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of categories per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Pagination page number.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "examples": [
          {
            "name": "Categories for a board",
            "request": {
              "query": {
                "board_id": "11111111-1111-1111-1111-111111111111",
                "limit": 10
              }
            },
            "notes": "Pair this with the board_id you plan to use on the ticket so category selections stay consistent."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/users"
      },
      "metadata": {
        "displayName": "List Users",
        "summary": "Fetch users/technicians",
        "description": "Lists tenant users. Use this to discover the user_id for the assignee field on a ticket.",
        "parameters": [
          {
            "name": "search_term",
            "in": "query",
            "required": false,
            "description": "Match against name or email.",
            "schema": { "type": "string" }
          },
          {
            "name": "team_id",
            "in": "query",
            "required": false,
            "description": "Filter users belonging to a specific team.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of users per page (default 25, max 100).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
          }
        ],
        "examples": [
          {
            "name": "Find a technician",
            "request": {
              "query": {
                "search_term": "Samantha",
                "limit": 5
              }
            },
            "notes": "Use the result set to map the human name back to a user_id for the assigned_to field."
          }
        ]
      }
    },
    {
      "match": {
        "method": "get",
        "path": "/api/v1/tags"
      },
      "metadata": {
        "displayName": "List Tags",
        "summary": "Fetch tag catalog",
        "description": "Returns tags configured for the tenant. Reuse these when populating the tags array for a ticket.",
        "parameters": [
          {
            "name": "entity_type",
            "in": "query",
            "required": false,
            "description": "Limit results to tags used for a specific entity type (e.g., ticket).",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of tags per page (default 25, max 200).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200 }
          }
        ],
        "examples": [
          {
            "name": "Retrieve ticket tags",
            "request": {
              "query": {
                "entity_type": "ticket",
                "limit": 25
              }
            },
            "notes": "Use existing tag names whenever possible rather than inventing new ones."
          }
        ]
      }
    }
  ]
}