openapi: 3.2.0
info:
  title: Lucra Forge Locations API
  description: "See https://docs.lucrasports.com/lucra-sdk/sdks-and-apis for implementation details.\n\n---\n\n## Environments\n\n| Environment | Base URL |\n|-------------|----------|\n| Sandbox | `https://forge.sandbox.lucrasports.com` |\n| Production | `https://forge.lucrasports.com` |\n\nUse sandbox for development and testing. Production credentials are separate and should only be used in live environments.\n\n---\n\n## Authentication\n\nAll requests require an API key passed in the `X-Lucra-Api-Key` header. Keys are provisioned by the Lucra team.\n\n```bash\ncurl https://forge.sandbox.lucrasports.com/api/<endpoint> \\\n  -H \"X-Lucra-Api-Key: <your-api-key>\"\n```\n\n> **Note:** Unlike the legacy API, query parameter and request body authentication are not supported.\n\n---\n\n## Rate Limiting\n\nAll API requests are rate-limited per API key using a fixed-window strategy. Each key is allowed up to **100 requests per 10-second window**.\n\nWhen the limit is exceeded, the API responds with **429 Too Many Requests**.\n"
  version: '1.0'
  contact: {}
servers:
- url: /
  description: Current host
- url: https://forge.lucrasports.com
  description: Production
- url: https://forge.sandbox.lucrasports.com
  description: Sandbox
tags:
- name: Locations
paths:
  /api/v1/locations:
    post:
      description: 'Creates a new location.


        Returns the created location with its generated `id`.'
      operationId: LocationsController_create_v1
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLocationDto'
      responses:
        '201':
          description: Location created successfully
          headers:
            X-Request-Id:
              description: Unique request identifier for tracing and debugging.
              schema:
                type: string
              example: req_abc123
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationResponseDto'
      security:
      - api-key: []
      summary: Create Location
      tags:
      - Locations
    get:
      description: 'Returns a paginated list of locations.


        Supports optional filtering by `state` and `city` (case-insensitive). Standard pagination via `limit` and `offset` query parameters.'
      operationId: LocationsController_findAll_v1
      parameters:
      - name: state
        required: false
        in: query
        description: Filter by state abbreviation (case-insensitive)
        schema:
          example: TX
          type: string
      - name: city
        required: false
        in: query
        description: Filter by city name (case-insensitive)
        schema:
          example: Austin
          type: string
      - name: limit
        required: false
        in: query
        description: Number of items to return per page
        schema:
          minimum: 1
          maximum: 100
          default: 25
          type: number
      - name: offset
        required: false
        in: query
        description: Number of items to skip before returning results
        schema:
          minimum: 0
          default: 0
          type: number
      responses:
        '200':
          description: Location list retrieved successfully
          headers:
            X-Request-Id:
              description: Unique request identifier for tracing and debugging.
              schema:
                type: string
              example: req_abc123
            Link:
              description: 'Pagination links per RFC 8288. Relations: `next`, `prev`, `first`.'
              schema:
                type: string
              example: </tournaments/abc/leaderboard?limit=25&offset=25>; rel="next", </tournaments/abc/leaderboard?limit=25&offset=0>; rel="first"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationResponseDto'
      security:
      - api-key: []
      summary: List Locations
      tags:
      - Locations
components:
  schemas:
    LocationResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the location
          example: 123e4567-e89b-12d3-a456-426614174000
        name:
          type:
          - object
          - 'null'
          description: Display name of the location
          example: Main Arena
        streetAddress:
          type:
          - object
          - 'null'
          description: Street address
          example: 123 Main St
        unit:
          type:
          - object
          - 'null'
          description: Unit or suite number
          example: Suite 400
        city:
          type:
          - object
          - 'null'
          description: City
          example: Austin
        state:
          type:
          - object
          - 'null'
          description: State abbreviation
          example: TX
        country:
          type:
          - object
          - 'null'
          description: Country code
          example: US
        postalCode:
          type:
          - object
          - 'null'
          description: Postal or ZIP code
          example: '78701'
        displayName:
          type:
          - object
          - 'null'
          description: Human-readable display name shown in the UI
          example: Main Arena — Austin, TX
        tenantId:
          type: string
          description: Identifier of the tenant this location belongs to
          example: tenant_abc123
        createdAt:
          type:
          - object
          - 'null'
          description: Timestamp when the location was created
          example: '2025-01-01T00:00:00.000Z'
        updatedAt:
          type:
          - object
          - 'null'
          description: Timestamp when the location was last updated
          example: '2025-01-15T00:00:00.000Z'
      required:
      - id
      - name
      - streetAddress
      - unit
      - city
      - state
      - country
      - postalCode
      - displayName
      - tenantId
      - createdAt
      - updatedAt
    CreateLocationDto:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Display name of the location
          example: Main Arena
        streetAddress:
          type:
          - string
          - 'null'
          description: Street address
          example: 123 Main St
        unit:
          type:
          - string
          - 'null'
          description: Unit or suite number
          example: Suite 400
        city:
          type:
          - string
          - 'null'
          description: City
          example: Austin
        state:
          type:
          - string
          - 'null'
          description: State abbreviation
          example: TX
        country:
          type:
          - string
          - 'null'
          description: Country code
          example: US
        postalCode:
          type:
          - string
          - 'null'
          description: Postal or ZIP code
          example: '78701'
        displayName:
          type:
          - string
          - 'null'
          description: Human-readable display name shown in the UI
          example: Main Arena — Austin, TX
      required:
      - name
  securitySchemes:
    X-Lucra-Api-Key:
      type: apiKey
      in: header
      name: X-Lucra-Api-Key
      description: API key for tenant authentication