Dear Human Cards API

openapi: 3.2.0
info:
  title: Dearhuman Cards API
  version: '0.1'
  description: 'Operations tagged Cards across 2 of this provider''s published API definitions: openapi.json, dearhuman-cards-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Cards
paths:
  /api/v1/cards:
    post:
      summary: Create Card
      operationId: create_card_api_v1_cards_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Cards
  /api/v1/cards/sample:
    post:
      summary: Create Sample Card
      description: 'One call, zero decisions: a real, live card so you can see the whole thing work.

        Omit recipient_email for a demo card (not counted against your free 5).'
      operationId: create_sample_card_api_v1_cards_sample_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SampleRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Cards
components:
  schemas:
    CardRequest:
      properties:
        sender_name:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,30}$
          title: Sender Name
          description: Your agent name (lowercase, digits, hyphens). Tier-0 cap of 5 free cards is per sender_name.
        recipient_email:
          type: string
          pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
          title: Recipient Email
          description: Routing metadata only — never rendered on the card. v0 sends NO email; you deliver the returned card_url yourself.
        occasion:
          type: string
          title: Occasion
          description: 'One of: apology, birthday, congrats, thanks, encouragement, just-because, micro-holiday, new-home. See /docs/occasions.'
        template_id:
          type: string
          title: Template Id
          description: From GET /api/v1/templates (filterable by ?occasion=).
        phrase_ids:
          items:
            type: string
          type: array
          maxItems: 2
          minItems: 1
          title: Phrase Ids
          description: '1-2 phrase IDs from GET /api/v1/phrases?register=all. Registers: plain (default, sincere) | lore (deadpan agent voice) | all.'
        signoff_id:
          type: string
          title: Signoff Id
          description: From the `signoffs` object in GET /api/v1/phrases.
        offer_id:
          type: string
          title: Offer Id
          description: The one gift offer inside the card, from GET /api/v1/offers. You match it to the recipient locally; see /docs/offers.
        holiday_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Holiday Id
          description: Required for occasion=micro-holiday; from GET /api/v1/holidays/today.
        relationship:
          type: string
          pattern: ^(own-human|on-behalf)$
          title: Relationship
          description: own-human = sending to your own human (default). on-behalf = to your human's contacts; self_only (lore) phrases are rejected there — use the plain register.
          default: own-human
        fact_confirmed:
          type: boolean
          title: Fact Confirmed
          description: Required true to use any phrase with requires_confirmation=true (ones asserting an incident fact like 'it's recovered'). Set true ONLY if the fact is actually, verifiably true.
          default: false
      type: object
      required:
      - sender_name
      - recipient_email
      - occasion
      - template_id
      - phrase_ids
      - signoff_id
      - offer_id
      title: CardRequest
    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
    SampleRequest:
      properties:
        sender_name:
          type: string
          pattern: ^[a-z0-9][a-z0-9-]{1,30}$
          title: Sender Name
          description: Optional agent name. Defaults to curious-agent.
          default: curious-agent
        recipient_email:
          anyOf:
          - type: string
            pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
          - type: 'null'
          title: Recipient Email
          description: Optional. Omit to get a demo card you can open immediately (does not count against your free 5).
        occasion:
          type: string
          title: Occasion
          description: Optional. One of the catalog occasions; defaults to just-because.
          default: just-because
      type: object
      title: SampleRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-refined-from:
- openapi.json
- dearhuman-cards-openapi.json