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

# Add Place By Id

> Save a place by id — optionally to a list. Idempotent per (place, list).

THE contract is a canonical place ULID (`canonical_places.id`) — the
spine identity every surface joins on; saves resolve entirely from the
spine with zero paid fetches, and dedup by canonical place_id.

A Google place_id is also accepted as the LEGACY autocomplete path (the
picker hands us a gpid before any canonical row exists); that path still
ends canonical — the resolver mints/links the row and stamps
`item.place_id` — it just pays the Google fetch to get there.



## OpenAPI

````yaml /openapi.json post /saved/add-place
openapi: 3.1.0
info:
  title: Stardrift API
  description: >-
    Read and edit the authenticated user's trips, itineraries, recorded
    bookings, and saved lists. Private records are owner-scoped. MCP tool names
    are documented separately from these HTTP operations.
  version: v1
servers:
  - url: https://stardrift.ai/api
security: []
paths:
  /saved/add-place:
    post:
      tags:
        - saved
      summary: Add Place By Id
      description: |-
        Save a place by id — optionally to a list. Idempotent per (place, list).

        THE contract is a canonical place ULID (`canonical_places.id`) — the
        spine identity every surface joins on; saves resolve entirely from the
        spine with zero paid fetches, and dedup by canonical place_id.

        A Google place_id is also accepted as the LEGACY autocomplete path (the
        picker hands us a gpid before any canonical row exists); that path still
        ends canonical — the resolver mints/links the row and stamps
        `item.place_id` — it just pays the Google fetch to get there.
      operationId: add_place_by_id_saved_add_place_post
      parameters:
        - name: x-client-id
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Client-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPlaceByIdRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedItemOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AddPlaceByIdRequest:
      properties:
        place_id:
          type: string
          title: Place Id
        list_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: List Id
        skip_enrichment:
          type: boolean
          title: Skip Enrichment
          default: false
      type: object
      required:
        - place_id
      title: AddPlaceByIdRequest
    SavedItemOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        list_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: List Id
        place_ref:
          type: string
          title: Place Ref
        place_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Place Id
        caption:
          anyOf:
            - type: string
            - type: 'null'
          title: Caption
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        name:
          type: string
          title: Name
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        lat:
          anyOf:
            - type: number
            - type: 'null'
          title: Lat
        lng:
          anyOf:
            - type: number
            - type: 'null'
          title: Lng
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        image_thumbhash:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Thumbhash
        rating:
          anyOf:
            - type: number
            - type: 'null'
          title: Rating
        num_reviews:
          anyOf:
            - type: integer
            - type: 'null'
          title: Num Reviews
        tabelog_tier:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tabelog Tier
        michelin:
          anyOf:
            - $ref: '#/components/schemas/MichelinDistinction'
            - type: 'null'
        source:
          type: string
          title: Source
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Url
        is_shared:
          type: boolean
          title: Is Shared
        review_state:
          anyOf:
            - type: string
            - type: 'null'
          title: Review State
        created_at:
          type: string
          title: Created At
      type: object
      required:
        - id
        - list_id
        - place_ref
        - place_id
        - caption
        - name
        - category
        - city
        - state
        - country
        - lat
        - lng
        - image_url
        - rating
        - num_reviews
        - source
        - source_url
        - is_shared
        - review_state
        - created_at
      title: SavedItemOut
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MichelinDistinction:
      properties:
        tier:
          type: string
          enum:
            - stars
            - bib_gourmand
            - selected
          title: Tier
        stars:
          anyOf:
            - type: integer
            - type: 'null'
          title: Stars
        green_star:
          type: boolean
          title: Green Star
          default: false
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        cuisine:
          anyOf:
            - type: string
            - type: 'null'
          title: Cuisine
      type: object
      required:
        - tier
      title: MichelinDistinction
      description: >-
        A place's Michelin Guide distinction, structured. Canonical rationale —

        the TS mirror and the renderers point here rather than restating it.


        Rides alongside `michelin_award` rather than replacing it: that field is
        a

        pre-rendered label ("★★★"), and a label cannot drive iconography. An
        award

        string we don't recognise yields NO distinction (we never paint a mark
        we

        can't justify) while still surfacing verbatim in `michelin_award`, so a

        new tier degrades to text rather than disappearing.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````