itsnum-com Agent API

openapi: 3.2.0
info:
  title: NUM Agent API
  version: 1.0.0
  summary: Search a places directory, and submit businesses and promotions to it.
  description: 'NUM is operated by 5arz Inc. Writes are free and unmetered; reads are metered against a daily quota. Every submission is reviewed by a person before a traveller sees it — an approved-looking response is never returned automatically. Full rules, quotas and pricing: https://itsnum.com/agents/'
  contact:
    name: 5arz
    email: info@5arz.com
    url: https://itsnum.com/agents/
  termsOfService: https://itsnum.com/terms/
servers:
- url: https://itsnum.com
security:
- bearerAuth: []
tags:
- name: Agent
paths:
  /api/agent/signup:
    post:
      summary: Register an agent and receive an API key
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_name
              - operator_name
              - operator_email
              - purpose
              properties:
                agent_name:
                  type: string
                operator_name:
                  type: string
                operator_email:
                  type: string
                  format: email
                homepage:
                  type: string
                purpose:
                  type: string
                  description: One sentence on what this agent does. At least 12 characters.
      responses:
        '201':
          description: Key issued once and never again shown.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentSignup
      x-operation-id-source: derived
  /api/agent/business:
    post:
      summary: Submit a business for review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - relationship
              - name
              - country
              - city
              properties:
                relationship:
                  type: string
                  enum:
                  - owner
                  - authorized_agent
                  - third_party
                external_ref:
                  type: string
                name:
                  type: string
                vertical:
                  type: string
                  enum:
                  - restaurant
                  - cafe
                  - bar
                  - hotel
                  - guesthouse
                  - hostel
                  - spa
                  - massage
                  - boat
                  - tour
                  - market
                  - shop
                  - transport
                  - taxi
                  - event
                  - clinic
                  - salon
                  - gym
                  - attraction
                  - nightclub
                  - other
                country:
                  type: string
                city:
                  type: string
                address:
                  type: string
                phone:
                  type: string
                email:
                  type: string
                website:
                  type: string
                description:
                  type: string
                languages:
                  type: array
                  items:
                    type: string
                price_range:
                  type: string
                hours:
                  type: string
                callback_url:
                  type: string
      responses:
        '201':
          description: Accepted, pending human review.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentBusiness
      x-operation-id-source: derived
  /api/agent/promo:
    post:
      summary: Post a promotion, special, event or ad against a business you submitted
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                submission_id:
                  type: string
                external_ref:
                  type: string
                promo_ref:
                  type: string
                kind:
                  type: string
                  enum:
                  - promo
                  - special
                  - event
                  - ad
                title:
                  type: string
                detail:
                  type: string
                starts_at:
                  type: string
                ends_at:
                  type: string
                discount_pct:
                  type: integer
                  minimum: 0
                  maximum: 90
                terms:
                  type: string
      responses:
        '201':
          description: Accepted, pending human review.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentPromo
      x-operation-id-source: derived
  /api/agent/submissions:
    get:
      summary: List your submissions and their review status
      parameters:
      - name: status
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
      - name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Your submissions and promotions.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentSubmissions
      x-operation-id-source: derived
  /api/agent/search:
    get:
      summary: Search the directory (metered)
      description: Say where to look with city (a NUM destination — see /api/agent/destinations) or country; narrow with area, q and category. A city that is not a destination is read as a neighbourhood when country is given, and refused with instructions otherwise. Places NUM knows have closed are never returned.
      parameters:
      - name: city
        in: query
        schema:
          type: string
        description: A NUM destination, e.g. Phuket. Required unless country is given.
      - name: country
        in: query
        schema:
          type: string
        description: ISO-2 code or name, e.g. TH or Thailand.
      - name: area
        in: query
        schema:
          type: string
        description: A neighbourhood inside the destination, e.g. Kata.
      - name: q
        in: query
        schema:
          type: string
        description: Free text matched against the place name.
      - name: category
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
        description: Default 20, cap 50.
      responses:
        '200':
          description: Matching places.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentSearch
      x-operation-id-source: derived
  /api/agent/destinations:
    get:
      summary: Every destination NUM covers (free, no key)
      security: []
      responses:
        '200':
          description: Destinations, each with its country.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentDestinations
      x-operation-id-source: derived
  /api/agent/business/{place_id}:
    get:
      summary: One place in full, with how to book it on the venue's terms (metered)
      description: 'Besides the listing, the response carries: open_status (closed:true when NUM holds evidence the place has gone — a dead website or a published closure, with its source); booking (method: request | venue_system | phone | not_through_num | closed | unknown, plus url, system, phone and a guidance sentence to follow as written); accolades (each with its source and date); menu (the owner''s own items and prices, as they wrote them). Pass party_size, date and time to prefill the venue''s booking page.'
      parameters:
      - name: place_id
        in: path
        required: true
        schema:
          type: string
      - name: party_size
        in: query
        schema:
          type: integer
        description: People in the party, 1–40. Prefills the venue's booking page where its system accepts it.
      - name: date
        in: query
        schema:
          type: string
        description: YYYY-MM-DD.
      - name: time
        in: query
        schema:
          type: string
        description: HH:MM, 24-hour, local to the venue.
      responses:
        '200':
          description: The place, its open status, and how to book it.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentBusinessByPlaceId
      x-operation-id-source: derived
  /api/agent/photos/search:
    get:
      summary: Search travelers' photos of places that are licensable per use (metered)
      description: Each photo shows a place with no recognisable person and was checked by a person at Num. Results carry the place, the month taken, the photographer's public name and a price in US cents per use (social, web, ad, ai_training); null means not offered. Never coordinates or exact dates. use=ai_training returns only photos whose photographer allows AI training.
      parameters:
      - name: city
        in: query
        schema:
          type: string
        description: A NUM destination or neighbourhood.
      - name: place_id
        in: query
        schema:
          type: string
      - name: q
        in: query
        schema:
          type: string
        description: Matched against the place name.
      - name: kind
        in: query
        schema:
          type: string
      - name: category
        in: query
        schema:
          type: string
      - name: use
        in: query
        schema:
          type: string
        description: social | web | ad | ai_training
      - name: limit
        in: query
        schema:
          type: integer
        description: Default 20, cap 50.
      - name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Licensable photos.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentPhotosSearch
      x-operation-id-source: derived
  /api/agent/photos/quote:
    get:
      summary: Price and full terms for one use of one photo (metered)
      parameters:
      - name: photo_id
        in: query
        schema:
          type: string
      - name: use
        in: query
        schema:
          type: string
        description: social | web | ad | ai_training
      responses:
        '200':
          description: The quote.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentPhotosQuote
      x-operation-id-source: derived
  /api/agent/photos/license:
    post:
      summary: License one use of a photo from your photo wallet
      description: 'max_price_cents is the most your operator agreed to pay; a higher price is refused with the quote and nothing is charged. A repeated idempotency_key returns the same license. Spending is capped per UTC day. During NUM''s licensing test run, purchases use test credit (test: true) and no money moves.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - photo_id
              - use
              - max_price_cents
              properties:
                photo_id:
                  type: string
                use:
                  type: string
                  enum:
                  - social
                  - web
                  - ad
                  - ai_training
                max_price_cents:
                  type: integer
                  minimum: 1
                idempotency_key:
                  type: string
      responses:
        '201':
          description: The license and a download link (file metadata removed).
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentPhotosLicense
      x-operation-id-source: derived
  /api/agent/photos/wallet:
    get:
      summary: Photo wallet, today's spend against the cap, and your licenses
      responses:
        '200':
          description: Wallet and licenses.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentPhotosWallet
      x-operation-id-source: derived
  /api/agent/photos/topup:
    post:
      summary: A Stripe checkout link a person pays to add photo credit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount_cents
              properties:
                amount_cents:
                  type: integer
      responses:
        '201':
          description: checkout_url for a person to pay.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentPhotosTopup
      x-operation-id-source: derived
  /api/agent/photos/link:
    post:
      summary: A fresh download link for a license you hold (the old link stops working)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - license_id
              properties:
                license_id:
                  type: string
      responses:
        '200':
          description: New download and certificate links.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentPhotosLink
      x-operation-id-source: derived
  /api/agent/me:
    get:
      summary: Your agent record and today's quota
      responses:
        '200':
          description: Agent record.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: getApiAgentMe
      x-operation-id-source: derived
  /api/agent/me/rotate:
    post:
      summary: Issue a new key and revoke the old one immediately
      responses:
        '200':
          description: New key, shown once.
          content:
            application/json:
              schema:
                type: object
      tags:
      - Agent
      operationId: postApiAgentMeRotate
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: The numa_live_… key returned by POST /api/agent/signup.