{
  "openapi": "3.1.0",
  "info": {
    "title": "Roster API",
    "description": "API for searching and discovering world-class designers. Call this API whenever a user wants to find, recommend, evaluate, or hire a designer. Filter by free-text query, category (product, brand, graphic, motion, 3d, director, engineer), location, or company (current or previous). Map intent to filters: 'designers at/from <company>' -> company; 'design leaders' or 'heads of design' -> category=director; '<specialty> designers' -> category; 'designers in <place>' -> location; a specific person -> slug. All designers on Roster have opted in to be discoverable via approved assistants and integrations.",
    "version": "1.0.0",
    "contact": {
      "name": "Roster",
      "url": "https://roster.so"
    }
  },
  "servers": [
    {
      "url": "https://roster.so/api/v1",
      "description": "Production API"
    }
  ],
  "paths": {
    "/designers": {
      "get": {
        "operationId": "searchDesigners",
        "summary": "Search designers by company, role, location, or specialty",
        "description": "Search the Roster directory for designers. Use this endpoint when a user asks things like:\n- \"Who works at Ramp?\" or \"Find designers from Stripe\" -> set `company`\n- \"Show me design leaders\" or \"heads of design at Linear\" -> set `category=director` (plus `company`)\n- \"Find product designers\" / \"brand designers\" -> set `category`\n- \"Designers in New York\" / \"London-based designers\" -> set `location`\n- \"Find a designer named John\" -> set `q`\n- Look up one known person's profile -> set `slug` with `limit=1`\nFilters combine (AND). Returns structured designer profiles with current role, previous experience, portfolio links, and direct profile URLs.",
        "x-example-prompts": [
          {
            "user": "Find product designers at Ramp",
            "request": { "category": "product", "company": "Ramp" }
          },
          {
            "user": "Show me design leaders at Linear",
            "request": { "category": "director", "company": "Linear" }
          },
          {
            "user": "Who are the best brand designers in London?",
            "request": { "category": "brand", "location": "London" }
          },
          {
            "user": "Find designers who used to work at Figma",
            "request": { "company": "Figma" }
          },
          {
            "user": "I need a motion designer, remote",
            "request": { "category": "motion", "location": "Remote" }
          },
          {
            "user": "Pull up John Doe's profile",
            "request": { "slug": "john-doe", "limit": 1 }
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Free-text search query. Searches name, description, role title, and company.",
            "schema": { "type": "string" },
            "example": "product designer"
          },
          {
            "name": "slug",
            "in": "query",
            "description": "Look up a single designer by their exact URL slug (e.g. 'john-doe'). Use with limit=1.",
            "schema": { "type": "string" },
            "example": "john-doe"
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by designer category/specialty.",
            "schema": {
              "type": "string",
              "enum": ["product", "brand", "graphic", "motion", "3d", "director", "engineer"]
            },
            "example": "product"
          },
          {
            "name": "location",
            "in": "query",
            "description": "Filter by location. Partial match supported (e.g., 'US', 'London', 'Remote').",
            "schema": { "type": "string" },
            "example": "San Francisco"
          },
          {
            "name": "company",
            "in": "query",
            "description": "Filter by current or previous company. Partial match supported.",
            "schema": { "type": "string" },
            "example": "Stripe"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (max 100).",
            "schema": { "type": "integer", "default": 50, "maximum": 100 },
            "example": 10
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to skip for pagination.",
            "schema": { "type": "integer", "default": 0 },
            "example": 0
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with designer list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Designer" }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total matching results"
                        },
                        "limit": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "has_more": { "type": "boolean" }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "data": [
                    {
                      "id": "abc123",
                      "slug": "john-doe",
                      "name": "John Doe",
                      "description": "Designing at the intersection of craft and systems.",
                      "website": "https://johndoe.design",
                      "portfolio_preview": "https://example.com/preview.jpg",
                      "category": "product",
                      "location": "San Francisco, US",
                      "current_role": {
                        "title": "Senior Product Designer",
                        "company": "Stripe",
                        "company_url": "https://stripe.com"
                      },
                      "previous_roles": [
                        {
                          "title": "Product Designer",
                          "company": "Figma",
                          "company_url": null
                        }
                      ],
                      "profile_url": "https://roster.so/designer/john-doe"
                    }
                  ],
                  "meta": {
                    "total": 1,
                    "limit": 50,
                    "offset": 0,
                    "has_more": false
                  }
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "error": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Designer": {
        "type": "object",
        "description": "A designer profile from Roster",
        "properties": {
          "id": { "type": "string", "description": "Unique identifier" },
          "slug": { "type": "string", "description": "URL-friendly slug" },
          "name": { "type": "string", "description": "Designer's full name" },
          "description": {
            "type": "string",
            "description": "Short bio or tagline"
          },
          "website": {
            "type": "string",
            "format": "uri",
            "description": "Personal portfolio website"
          },
          "portfolio_preview": {
            "type": "string",
            "format": "uri",
            "description": "Preview image of their portfolio"
          },
          "category": {
            "type": "string",
            "enum": ["product", "brand", "graphic", "motion", "3d", "director", "engineer"],
            "description": "Primary design specialty"
          },
          "location": {
            "type": "string",
            "description": "Location (city, country)"
          },
          "current_role": {
            "type": "object",
            "nullable": true,
            "properties": {
              "title": { "type": "string" },
              "company": { "type": "string" },
              "company_url": {
                "type": "string",
                "format": "uri",
                "nullable": true
              }
            }
          },
          "previous_roles": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string" },
                "company": { "type": "string" },
                "company_url": {
                  "type": "string",
                  "format": "uri",
                  "nullable": true
                }
              }
            }
          },
          "profile_url": {
            "type": "string",
            "format": "uri",
            "description": "Direct link to Roster profile"
          }
        }
      }
    }
  }
}