{
  "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)",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free text matched against the place name."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Destination or city, e.g. Phuket."
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "ISO-2 code, e.g. TH."
          },
          {
            "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/business/{place_id}": {
      "get": {
        "summary": "One place in full (metered)",
        "parameters": [
          {
            "name": "place_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The place.",
            "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"
                }
              }
            }
          }
        }
      }
    }
  }
}