> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.sandbox.blitzboardstats.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create player

> Create a player on a team. Requires an idem-key header.

export const IdempotencyKeyGenerator = () => {
  const createKey = () => {
    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
      return crypto.randomUUID();
    }
    return ('xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx').replace(/[xy]/g, char => {
      const random = Math.random() * 16 | 0;
      const value = char === 'x' ? random : random & 0x3 | 0x8;
      return value.toString(16);
    });
  };
  const [key, setKey] = useState(createKey);
  const [copied, setCopied] = useState(false);
  const handleGenerate = () => {
    setKey(createKey());
    setCopied(false);
  };
  const handleCopy = async () => {
    try {
      await navigator.clipboard.writeText(key);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch (_error) {
      setCopied(false);
    }
  };
  return <div className="not-prose my-4 rounded-xl border border-zinc-950/10 bg-zinc-50 p-4 dark:border-white/10 dark:bg-zinc-900/40">
      <p className="mb-1 text-sm font-medium text-zinc-950 dark:text-white">
        Test here — you can use this UUID
      </p>
      <p className="mb-3 text-sm text-zinc-950/70 dark:text-white/70">
        Copy it into the <code className="rounded bg-zinc-950/5 px-1 py-0.5 text-xs dark:bg-white/10">idem-key</code> header
        in Try it or curl. Generate a new value for every new player create.
      </p>
      <div className="flex flex-col gap-3 sm:flex-row sm:items-center">
        <code className="block min-w-0 flex-1 overflow-x-auto rounded-lg border border-zinc-950/10 bg-white px-3 py-2 font-mono text-sm text-zinc-950 dark:border-white/10 dark:bg-zinc-950 dark:text-white">
          {key}
        </code>
        <div className="flex shrink-0 gap-2">
          <button type="button" onClick={handleGenerate} className="rounded-lg border border-zinc-950/10 bg-white px-3 py-2 text-sm font-medium text-zinc-950 hover:bg-zinc-100 dark:border-white/10 dark:bg-zinc-950 dark:text-white dark:hover:bg-zinc-800">
            Generate
          </button>
          <button type="button" onClick={handleCopy} className="rounded-lg bg-teal-700 px-3 py-2 text-sm font-medium text-white hover:bg-teal-800 dark:bg-teal-600 dark:hover:bg-teal-500">
            {copied ? 'Copied' : 'Copy'}
          </button>
        </div>
      </div>
    </div>;
};

## `idem-key` (required)

Client-generated unique string for this create. Send it as header `idem-key` (or `Idempotency-Key`).

* **Same key again** → `409 Conflict` (`Idempotency key already used`); no second player is created.
* **New player** → always generate a new key (UUID recommended).

Use the generator below to create an `idem-key` you can paste into Try it.

<IdempotencyKeyGenerator />

See [Concepts → Idempotency key](/concepts#idempotency-key-idem-key) for the full definition.


## OpenAPI

````yaml openapi.json POST /v1/blitz-api/teams/{teamId}/players
openapi: 3.0.3
info:
  title: BlitzBoard Public API
  version: 1.0.0
  description: >-
    Organization-scoped public integration API for seasons, teams, players,
    schedules, and team player statistics.

    Authenticate with `Authorization: Bearer bb_live_...` (API key, not a login
    JWT).

    Generate keys from Organizations → organization detail at
    https://live.blitzboardstats.com/organizations.

    List seasons via GET /v1/blitz-api/seasons and pass `_id` as `season` when
    creating a team.
servers:
  - url: https://sandbox.blitzboardstats.com/api
    description: Sandbox
security:
  - ApiKeyBearer: []
tags:
  - name: Seasons
    description: List seasons to use when creating teams
  - name: Teams
    description: Team CRUD scoped to the API key organization
  - name: Players
    description: Players under a team
  - name: Schedules
    description: Schedule events under a team
paths:
  /v1/blitz-api/teams/{teamId}/players:
    post:
      tags:
        - Players
      summary: Create player
      description: >-
        Create a single player. Requires header idem-key (or Idempotency-Key): a
        client-generated unique string for this create intent. Reusing a key
        that already created a player returns 409 Conflict and does not create a
        duplicate. Generate a new key for every new player. See Concepts →
        Idempotency key.
      operationId: createPlayer
      parameters:
        - name: teamId
          in: path
          required: true
          schema:
            type: string
            example: 507f1f77bcf86cd799439011
        - name: idem-key
          in: header
          required: true
          description: >-
            Client-generated unique string for this create intent (UUID
            recommended). Also accepted as Idempotency-Key. Same key reused
            after a successful create → 409 Conflict (Idempotency key already
            used). Missing → 400.
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlayerRequest'
            examples:
              default:
                summary: Request body
                value:
                  name: Alex Johnson
                  email: alex@example.com
                  position:
                    - QUARTERBACK
                  jerseyNumber: '10'
      responses:
        '201':
          description: Player created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    message: Players created successfully!
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    CreatePlayerRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: Alex Johnson
        email:
          type: string
          format: email
        position:
          type: array
          items:
            type: string
          example:
            - QUARTERBACK
      additionalProperties: true
      example:
        name: Alex Johnson
        email: alex@example.com
        position:
          - QUARTERBACK
        jerseyNumber: '10'
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          example: API key revoked successfully!
      example:
        message: API key revoked successfully!
    ErrorResponse:
      type: object
      properties:
        error:
          type: number
        message:
          type: string
        timestamp:
          type: string
          format: date-time
        traceId:
          type: string
      example:
        error: 40101
        message: Invalid API key
        timestamp: '2026-09-13T14:45:41.317Z'
        traceId: req_41f0e6c8a5ea232a
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Outside API key organization scope or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Public integration API key (`bb_live_...`). Not a login JWT.

````