{
  "openapi": "3.1.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. 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": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The numa_live_… key returned by POST /api/agent/signup."
      }
    }
  },
  "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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/me": {
      "get": {
        "summary": "Your agent record and today's quota",
        "responses": {
          "200": {
            "description": "Agent record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/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"
                }
              }
            }
          }
        }
      }
    }
  }
}