canonical: https://jentic.com/apis/itsnum.com/itsnum # Itsnum NUM Agent API The NUM Agent API lets AI agents search NUM's traveller directory of places such as restaurants, hotels, tours, spas, and shops by destination city or country, and read one place in full with its open status and how to book it on the venue's terms. Agents can also submit businesses and post promotions, specials, events, or ads against them, and every submission is reviewed by a person before a traveller sees it. A photo marketplace returns person-checked photos of places with a per-use price in US cents for social, web, ad, or ai_training use, and licenses a use from a prepaid wallet with a daily spending cap. ## For AI agents Search NUM's traveller directory by destination, read a place's open status and booking method, submit businesses and promotions for human review, and license place photos per use from a capped wallet. ## Scope Does not book flights, take hotel reservations, or process traveller payments. Use for NUM directory search, listing submissions, and place photo licensing only. ## Capabilities - Search the directory by city or country and narrow by area, q, and category, with closed places never returned - Read one place by place_id with its open_status and booking method, from request or venue_system to phone - Submit a business for human review with its name, vertical such as restaurant or hotel, country, and city - Post a promotion, special, event, or ad against a business you submitted - Search licensable photos of places and get a quote for one use such as web or ai_training - License one photo use from the wallet within a max_price_cents ceiling, with an idempotency_key for safe retries ## Use cases ### Agent travel planning with bookable places An AI travel agent building an itinerary needs places that are open and a clear way to book each one. Through Jentic the agent searches for 'find places to eat in a destination', loads the NUM directory search, and then reads each candidate's full record, which carries open_status and a booking method with url, system, or phone. The numa_live_ key is injected at call time, so the agent works from the listings without handling the credential. Example prompt: Call GET `/api/agent/destinations`, then GET `/api/agent/search` with a covered city and category restaurant, and GET `/api/agent/business/{place_id}` with party_size 4 for the top result to report its booking method ### Listing a business for travellers An agency managing local businesses submits them to NUM on the owner's behalf. The business submission takes a relationship of owner, authorized_agent, or third_party, a name, country, and city, with optional vertical, hours, and languages, and every submission is reviewed by a person before travellers see it. The submissions list reports review status, and a callback_url can receive the outcome. Example prompt: Call POST `/api/agent/business` with relationship authorized_agent, name Sea Breeze Cafe, vertical cafe, country TH, and city Koh Phangan, then call GET `/api/agent/submissions` with status to check its review ### Promoting specials and events A venue running a happy hour or hosting an event wants it in front of travellers. The promo operation posts a promo, special, event, or ad with a title and optional detail, start and end times, discount_pct, and terms, tied to a business you submitted by submission_id or external_ref. Example prompt: Call POST `/api/agent/promo` with submission_id from a prior submission, kind special, title Sunset happy hour, and discount_pct 20 ### Licensing place photos within a budget A content team needs photos of real places for a travel guide and an operator-set spending limit. Photo search returns person-checked images with no recognisable people and a price per use, the quote operation returns price and full terms, and the license operation refuses any price above max_price_cents without charging. Spending is capped per UTC day and the wallet shows today's spend. Example prompt: Call GET `/api/agent/photos/search` with city and use web, GET `/api/agent/photos/quote` for the first photo_id, then POST `/api/agent/photos/license` with photo_id, use web, and max_price_cents 500 ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/api/agent/search` | Search the directory | | GET | `/api/agent/business/{place_id}` | Get one place with booking details | | GET | `/api/agent/destinations` | List covered destinations | | POST | `/api/agent/business` | Submit a business for review | | POST | `/api/agent/promo` | Post a promotion against a business | | GET | `/api/agent/photos/search` | Search licensable photos | | POST | `/api/agent/photos/license` | License one photo use | | POST | `/api/agent/signup` | Register an agent and receive a key | ## Key resources - **Directory** — Destinations, place search, and full place records with open status and booking method - **Submissions** — Business and promotion submissions with human review and status listing - **Photos** — Photo search, per-use quotes, licensing, wallet, top-up checkout links, and fresh download links - **Agent account** — Signup for a key, agent record and quota, and key rotation ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 42 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 74 / 100 - Developer Experience & Jentic Compatibility: 56 / 100 - AI-Readiness & Agent Experience: 18 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 68 / 100 - **View full report:** https://jentic.com/apis/itsnum.com/itsnum/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring NUM by hand means signing up for a numa_live_ key, sending it as a bearer token, tracking the daily read quota, and rotating the key when needed. Through Jentic you install once, import the NUM Agent API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** NUM splits directory reads, submissions, and photo purchases into separate operations, and most targets travel in the query or request body, so rules bound which operations your agent may call rather than which place. You choose the operations it may call, so spending actions like POST `/api/agent/photos/license` or key rotation are not included unless you add them. - **Credential handling:** Your NUM key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find places in a travel destination' or 'submit a business listing', and Jentic returns the matching NUM operation with its input schema, including the vertical and kind enums, so the agent calls the right endpoint. ## Related APIs - **Yelp** — Business search and reviews across many cities - **Foursquare Places** — Global places search and point-of-interest details - **Viator** — Tours and activities inventory with bookable products ## FAQ ### What authentication does the NUM Agent API use? Per its OpenAPI spec, operations take a bearer token: the numa_live_ key returned by POST `/api/agent/signup.` Signup and GET `/api/agent/destinations` need no key, and POST `/api/agent/me/rotate` issues a new key and revokes the old one immediately. Through Jentic the key is stored by your own instance and attached at call time, so the agent never sees it. ### What are the rate limits for the NUM Agent API? The spec states that writes are free and unmetered while reads are metered against a daily quota, and GET `/api/agent/me` returns today's quota. It does not give the numbers; see https://itsnum.com/agents/ for current quotas and pricing. ### Does the NUM Agent API publish my submission straight away? No. Every business and promotion submission is reviewed by a person before a traveller sees it, and an approved-looking response is never returned automatically. GET `/api/agent/submissions` lists your submissions with their review status. ### Is there a NUM MCP server? You don't need an MCP server to give your agent NUM. Jentic connects it directly from the API Directory: import it, store your key once, and your agent calls the search, submission, and photo operations it needs without loading another server's tool definitions into its context. ### Can I limit what my agent is allowed to do with the NUM Agent API? Yes. Write a rule that allows only GET `/api/agent/search`, GET `/api/agent/destinations`, and GET `/api/agent/business/{place_id}`, for example, and the agent can plan trips from the directory but cannot license photos, request wallet top-ups, or rotate your key. Every call it makes is logged. ### How do I search NUM's directory through Jentic? Search Jentic for 'find places in a travel destination', load the GET `/api/agent/search` operation, and execute it with a city from GET `/api/agent/destinations` or a country, plus optional area, q, and category. To run it on your own infrastructure, install Jentic One from its GitHub repo.