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

# Tag Profiles

> Backfill tags onto existing profiles you own.

Sets each submitted tag only where the profile has no tag yet; existing
tags are never overwritten. Every entry lands in exactly one response
bucket, so partial application is normal and resubmitting the same
mapping is safe.



## OpenAPI

````yaml https://api.photalabs.com/v1/phota/openapi.json post /v1/phota/profiles/tags
openapi: 3.1.0
info:
  title: Phota API
  description: Create and manage profiles for photo editing and enhancement.
  version: v0.7.0
servers:
  - url: https://api.photalabs.com
security: []
tags:
  - name: Studio
    description: Image editing, generation, and enhancement.
  - name: Profiles
    description: 'Profile lifecycle: create, query, delete.'
paths:
  /v1/phota/profiles/tags:
    post:
      tags:
        - Profiles
      summary: Tag Profiles
      description: |-
        Backfill tags onto existing profiles you own.

        Sets each submitted tag only where the profile has no tag yet; existing
        tags are never overwritten. Every entry lands in exactly one response
        bucket, so partial application is normal and resubmitting the same
        mapping is safe.
      operationId: tag_profiles_v1_phota_profiles_tags_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagProfilesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagProfilesResponse'
        '401':
          description: Invalid API key in the X-API-Key header.
        '403':
          description: Missing X-API-Key header (no API key provided).
        '422':
          description: >-
            No image was produced (not charged, retryable), or request
            validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotaError422Response'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhotaError500Response'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TagProfilesRequest:
      properties:
        tags:
          items:
            $ref: '#/components/schemas/ProfileTagEntry'
          type: array
          maxItems: 1000
          minItems: 1
          title: Tags
          description: >-
            Profile-to-tag assignments to apply. Each profile may appear at most
            once.
      type: object
      required:
        - tags
      title: TagProfilesRequest
      description: Request body for backfilling tags onto existing untagged profiles.
      examples:
        - tags:
            - profile_id: 0ec2f38b1b5143de83f443266baa0027
              tag: user_abc123
            - profile_id: f75b1445f7274a94836102a2ae4d67d5
              tag: user_def456
    TagProfilesResponse:
      properties:
        updated:
          type: integer
          title: Updated
          description: Number of profiles whose tag was set by this request.
        already_tagged:
          items:
            type: string
          type: array
          title: Already Tagged
          description: >-
            Profiles that already carried the exact submitted tag (idempotent
            no-op).
        conflicts:
          items:
            $ref: '#/components/schemas/TagConflict'
          type: array
          title: Conflicts
          description: >-
            Profiles that already carry a different tag; existing tags are never
            overwritten.
        not_found:
          items:
            type: string
          type: array
          title: Not Found
          description: Profile ids that do not exist, are deleted, or are not owned by you.
      type: object
      required:
        - updated
        - already_tagged
        - conflicts
        - not_found
      title: TagProfilesResponse
      description: |-
        Per-outcome report for a tag-backfill request.

        Every requested profile lands in exactly one bucket, so
        ``updated + len(already_tagged) + len(conflicts) + len(not_found)``
        equals the number of submitted entries.
    PhotaError422Response:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable error message.
        code:
          type: string
          enum:
            - NO_IMAGE_GENERATED
            - INVALID_REQUEST
          title: Code
          description: Machine-readable error code.
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support.
      type: object
      required:
        - detail
        - code
        - request_id
      title: PhotaError422Response
      description: >-
        Error response for 422 Unprocessable Content.


        Covers the model completing without producing an image
        (``NO_IMAGE_GENERATED``,

        not charged, retryable) and request-body validation failures
        (``INVALID_REQUEST``).
    PhotaError500Response:
      properties:
        detail:
          type: string
          title: Detail
          description: Human-readable error message.
        code:
          type: string
          const: INTERNAL_ERROR
          title: Code
          description: Machine-readable error code.
        request_id:
          type: string
          title: Request Id
          description: Unique request identifier for support.
      type: object
      required:
        - detail
        - code
        - request_id
      title: PhotaError500Response
      description: Error response for 500 Internal Server Error.
    ProfileTagEntry:
      properties:
        profile_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Profile Id
          description: Identifier of the profile to tag.
        tag:
          type: string
          maxLength: 128
          minLength: 1
          title: Tag
          description: Tag to set (e.g., your end-user's identifier). Immutable once set.
      type: object
      required:
        - profile_id
        - tag
      title: ProfileTagEntry
      description: One profile -> tag assignment in a tag-backfill request.
    TagConflict:
      properties:
        profile_id:
          type: string
          title: Profile Id
          description: The profile that could not be tagged.
        existing_tag:
          type: string
          title: Existing Tag
          description: The tag the profile already carries.
      type: object
      required:
        - profile_id
        - existing_tag
      title: TagConflict
      description: A profile that already carries a different tag; it was left untouched.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````