Install Jentic One Beta

Connect the NUM Agent API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the NUM Agent API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fitsnum.com%2Fitsnum" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fitsnum.com%2Fitsnum" | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with NUM Agent API.

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

GET STARTED

Start building with NUM Agent API

Explore with Jentic One

View OpenAPI Document

Use Cases

Patterns agents use NUM Agent API for, with concrete tasks.

★ 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.

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.

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.

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.

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

15 endpoints — 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.

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

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

Why Jentic?

What agents get from Jentic-routed access to this vendor.

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 isolation

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.

Intent-based discovery

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.

FAQs

Specific to using NUM Agent API through Jentic.

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.

Itsnum NUM Agent API

AI ReadinessFoundational (D-)42/100

See full scorecard

Official vendor OpenAPI document · agent-readyMaps GeolocationPlaces Searchbearer15 EndpointsREST

For 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.

Use for: Find vegetarian restaurants in a NUM destination city, Get booking details for a guesthouse by its place id, List all destinations NUM covers, I want to submit my client's cafe to the NUM directory

Not supported: Does not book flights, take hotel reservations, or process traveller payments. Use for NUM directory search, listing submissions, and place photo licensing only.

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.

Jentic One on Github View OpenAPI Document

Show dimension breakdown

Foundational Compliance

Base layer of spec validity and structural soundness.

Grade: A-Signals: 4

98%

Lint Results

Aggregated quality score from linter diagnostics, weighted by severity.

100%

Resolution Completeness

Percentage of `$ref` references that resolve successfully.

100%

Specification Validity

Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).

Structural Integrity

Structural correctness score based on schema issues using logarithmic dampening.

Developer Experience & Jentic Compatibility

Clarity, completeness, and ingestion readiness for developers and tooling.

Grade: CSignals: 4

Example Density

How richly the API is illustrated with examples.

100%

Example Validity

Percentage of examples that conform to their schemas.

25%

Response Coverage

Percentage of operations with complete response definitions (success, client error, server error).

100%

Tooling Readiness

Health of API ingestion, bundling, and resolution within Jentic pipelines.

AI-Readiness & Agent Experience

Semantic breadth, depth, and agent comprehension for AI systems.

Grade: FSignals: 4

22%

Description Coverage

Coverage of descriptions across API elements.

Error Standardization

Coverage of RFC 9457 Problem Details for error responses.

OperationId Quality

Coverage, uniqueness, and casing consistency of operationIds for AI inference.

52%

Summary Coverage

Coverage of summaries across operations/tags/info.

Agent Usability

Functional utility, complexity comfort, and AI orchestration readiness.

Grade: A+Signals: 1

94%

Complexity Comfort

Agent comfort level based on API operational and structural complexity.

Security

Trust, risk posture, and security compliance.

Grade: B-Signals: 1

60%

Authentication Strength

Average quality of security schemes based on authentication method strength (weakest link for OAuth2).

AI Discoverability

Findability, semantic richness, and reasoning readiness.

Grade: B+Signals: 1

68%

Descriptive Richness

Clarity and depth of descriptions across API elements.

Connect the NUM Agent API to your agent

Capabilities

Start building with NUM Agent API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs

Itsnum NUM Agent API

Jentic AI Readiness Score

NUM Agent API

Foundational Compliance

Lint Results

Resolution Completeness

Specification Validity

Structural Integrity

Developer Experience & Jentic Compatibility

Example Density

Example Validity

Response Coverage

Tooling Readiness

AI-Readiness & Agent Experience

Description Coverage

Error Standardization

OperationId Quality

Summary Coverage

Agent Usability

Complexity Comfort

Security

Authentication Strength

AI Discoverability

Descriptive Richness