API for your agents

Who it is for

Companies that want an assistant to do the routine: answer "what should we offer a warehouse lead", list applicants waiting too long, post a vacancy from a brief, approve a pay run after a human has read the checks. The API is the same service layer the pages use, so anything the suite does will be reachable, with the same rules and the same role limits.

It is also the honest answer to "can I automate this": read-only endpoints are live now; write endpoints are listed with status "planned" and answer 501 until they are served, so an agent never guesses.

Minting a key

1. Open Settings › API keys. Only the company owner can mint; a fresh second lock is asked for first.
2. Name the key for what it does ("Claude agent", "payroll script"), pick the narrowest scopes that do the job, and choose when it expires.
3. Read the risks and tick the acknowledgement. The key is shown once; copy it to your agent's secret store and nowhere else.
4. Revoke it from the same page the moment you no longer need it. Revoking is instant.

In the demo anyone can mint a demo key (fjhr_demo_…). It acts on your demo company only and dies with it.

The risks, plainly

• A key is a password for the company. Whoever holds it can do everything its scopes allow, with no second lock.
• An agent acts in your name. A wrong instruction can close a vacancy, reject an applicant or change a record. Start with read scopes; add write scopes when the agent has earned them.
• Never paste a key into a public chat, a repository or a prompt someone else can read. Rotate when in doubt.
• Every call is logged with the key, the route, the status and the time. The owner reads the log on the same page.

Scopes

• market:read: pay bands and hiring difficulty.
• company:read: the company, Home and the counts.
• jobs:read and jobs:write: read, post, edit, close and bump vacancies.
• applications:read and applications:write: read applications and scores; move stages, reply, schedule interviews.
• people:read and people:write: employee records without private details; add and change people, decide leave.
• money:read and money:write: pay runs and rules; approve a pay run (files are prepared; no money moves).
• settings:write: webhooks and settings. Keys themselves can never be minted or changed by a key.
• all: everything above.

Calling it

Base URL https://hr.findjobs.ge/hr/api/v1. Send the key as Authorization: Bearer fjhr_live_… on every request. Answers are JSON. Add ?hl=ka, ru or tr to get summaries in that language where the API speaks.

Limits: 60 calls a minute and 20 writes a minute per key. A 429 carries Retry-After in seconds.

Errors are JSON with a stable code and a sentence: missing_key, invalid_key, scope, rate_limited, not_yet (designed, not served), not_found, server_error, and a docs link.

For an LLM agent

1. Give the agent https://hr.findjobs.ge/hr/api/v1/llms.txt: it describes the API, the limits and the rules in plain text.
2. Give it the OpenAPI document at https://hr.findjobs.ge/hr/api/v1/openapi.json to generate tools from.
3. Store the key in the agent's secret store, never in the prompt.
4. Tell it which scopes the key has, so it does not try what it cannot do.

Example: curl -H "Authorization: Bearer $KEY" "https://hr.findjobs.ge/hr/api/v1/market/pay-check?city=tbilisi&family=sales&offer=1200"

What a key can never do

• Read another company's data, or any job seeker's private data beyond what the company already sees on findjobs.ge.
• Move money, log in to a bank, or file with the Revenue Service.
• Mint or change keys, or weaken the second lock.
• Learn whether an employee has a findjobs profile or is applying elsewhere.

MCP server

The same API is served as a Model Context Protocol server at https://hr.findjobs.ge/hr/api/mcp (Streamable HTTP). Add it as a remote MCP server in Claude, ChatGPT, Cursor or any MCP host, with the company key as the bearer token; every endpoint appears as a tool, generated from the same registry, with the same scopes, limits and log.

Endpoints

The table below is generated from the same list the API routes from, so it cannot drift. Every endpoint listed answers today; scopes say what a key may do.