# Agents and LLMs > Give coding agents current, structured Semantil documentation. Use the smallest machine-readable entry point that fits the task. | Entry point | Best for | | --- | --- | | [`llms.txt`](/llms.txt) | A compact map for crawlers and agents | | [`llms-full.txt`](/llms-full.txt) | All guides in one plain-text context | | [`skill.md`](/skill.md) | Installing Semantil guidance as an agent skill | | [`openapi.yaml`](/openapi.yaml) | Generating clients and inspecting the complete API contract | | `PAGE_URL.md` | Reading an individual guide as clean Markdown | For example, the Markdown version of this page is available at [`/agents.md`](/agents.md). ## No documentation server required Agents can retrieve the raw Markdown and OpenAPI files directly over HTTPS. This keeps the source of truth inspectable and works with any client that can read a URL. ## Recommended agent context Give an implementation agent these URLs: ```text https://docs.semantil.com/llms.txt https://docs.semantil.com/openapi.yaml ``` Add `llms-full.txt` only when it needs the full conceptual documentation. This keeps the initial context small while preserving a deterministic source of truth. --- # Authentication > Authenticate with one API key per integration. Semantil accepts either header below on every authenticated endpoint. ```http Authorization: Bearer YOUR_API_KEY ``` ```http x-api-key: YOUR_API_KEY ``` Bearer authentication is the recommended default because most HTTP clients and agent frameworks support it directly. ## Key hygiene - Create one key per integration so it can be rotated or revoked independently. - Keep keys in environment variables or a secret manager, never in source control. - The full secret is shown once. Semantil stores only a hash afterward. - If a key leaks, revoke it in the dashboard and create a replacement. Never paste a Semantil API key into documentation search, an issue, or a prompt. Public docs, `llms.txt`, and the OpenAPI contract do not require a key. --- # Usage and credits > Read current usage information from Semantil and cap API requests safely. Semantil keeps plans, balances, and current credit units in the product services. This documentation deliberately does not duplicate a price list. ## Current sources of truth - [Pricing](https://semantil.com/pricing) publishes current plans and commercial terms. - [`GET /api/products`](https://semantil.com/api/products) publishes the current data products, fields, bundles, and credit units. - [`GET /api/me`](https://semantil.com/api#api-keys) returns the authenticated account's current plan, balance, and API capabilities. ## Charging behavior Domain enrichment is result-based: a selected product is charged only when it passes its quality gate and returns data. Missing domains and products that do not return data are not charged. ## Cap a request before it runs Read the current units from `GET /api/products`, then pass `max_credits` on a domain enrichment request. Semantil rejects the request before lookup when the selected products could exceed the limit. ```http GET /api/domains/example.com?products=profile,tech&max_credits={limit} ``` Responses expose the charged amount and remaining balance in credit headers, so integrations do not need a copied price table to track usage. --- # Errors > Handle stable problem codes and retry safely. Errors use `application/problem+json`. Branch on the stable `code` field rather than matching the human-readable message. ```json { "type": "https://semantil.com/problems/invalid-api-key", "title": "Invalid API key", "status": 401, "code": "invalid_api_key" } ``` ## Practical handling | Status | What to do | | --- | --- | | `400` | Fix the request; retrying unchanged will not help. | | `401` | Check or replace the API key. | | `403` | Use a key with access to the requested action. | | `429` | Respect `Retry-After`, then retry with backoff. | | `5xx` | Retry idempotent requests with exponential backoff and jitter. | The live [`GET /api/errors`](https://semantil.com/api/errors) endpoint lists the current problem codes without requiring an API key. --- # API examples > Copy practical requests for domain enrichment, company search, lookalikes, and market analysis. These examples use the production API. Start in the [Playground](https://semantil.com/api/playground) if you want to build and inspect the same requests in your browser. Set your key once before running an authenticated example: ```bash export SEMANTIL_API_KEY="your_api_key" ``` Read current products and usage units from [`GET /api/products`](https://semantil.com/api/products). The examples below deliberately do not copy a price list. ## Inspect available data Use the public product catalog before selecting domain data. No API key is required. ```bash curl "https://semantil.com/api/products" ``` The response lists current product IDs, descriptions, fields, bundles, and usage units. ## Enrich a company you already know Use domain enrichment when you have a company website and need structured facts about that specific business. ```bash curl --get "https://semantil.com/api/domains/notino.pl" \ -H "Authorization: Bearer $SEMANTIL_API_KEY" \ --data-urlencode "products=profile,tech" \ --data-urlencode "include=country,site_category,primary_platform,tech" ``` The request selects only the `profile` and `tech` products, then narrows the response to the fields needed by the integration. Omit `include` to receive all fields in the selected products. ## Search for companies in a target market Use search when you can describe the companies you want but do not yet know their domains. ```bash curl --get "https://semantil.com/api/search" \ -H "Authorization: Bearer $SEMANTIL_API_KEY" \ --data-urlencode "query=online fashion store" \ --data-urlencode "query_operator=and" \ --data-urlencode 'filters={"country":["Germany"]}' \ --data-urlencode "include=domain,company_name,country,primary_platform" \ --data-urlencode "limit=10" ``` The text query defines the business intent. `filters` narrows it with exact catalog values. Use the public [`GET /api/fields`](https://semantil.com/api/fields) catalog to discover filter names and their published value sources instead of guessing the contract. ## Find companies similar to a good example Use lookalike when you already know a representative customer, prospect, or competitor and want more companies with a similar profile. ```bash curl --get "https://semantil.com/api/lookalike/notino.pl" \ -H "Authorization: Bearer $SEMANTIL_API_KEY" \ --data-urlencode "k=10" \ --data-urlencode 'filters={"country":["Poland"]}' \ --data-urlencode "include=domain,company_name,country,primary_platform" \ --data-urlencode "include_evidence=true" ``` The seed domain provides the similarity signal. Filters constrain the candidate market, while `include_evidence=true` explains why candidates matched when evidence is available. ## Exclude companies already in your CRM Use `POST /api/search` when a search must omit a list of known customers or accounts. Send domains in the JSON body so they never appear in the URL. ```bash curl "https://semantil.com/api/search" \ -X POST \ -H "Authorization: Bearer $SEMANTIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "cosmetics manufacturer", "query_operator": "and", "filters": {"country": ["Poland"]}, "exclude_domains": ["existing-customer.pl", "current-account.com"], "include": "domain,company_name,country,site_category", "limit": 10 }' ``` Send the complete current exclusion list with each request. Semantil normalizes domains before applying the exclusions. ## Measure a market instead of returning companies Use a breakdown when you need a categorical distribution for a segment rather than individual company rows. ```bash curl --get "https://semantil.com/api/search" \ -H "Authorization: Bearer $SEMANTIL_API_KEY" \ --data-urlencode "query=online store" \ --data-urlencode "query_operator=and" \ --data-urlencode 'filters={"country":["Germany"]}' \ --data-urlencode "breakdown=primary_platform" \ --data-urlencode "population=ecommerce" \ --data-urlencode "breakdown_limit=10" ``` Only fields published as breakdown facets by `GET /api/fields` are accepted. The response describes the segment, field coverage, missing values, and the returned buckets. ## Inspect usage after a request Authenticated responses expose the charged amount and remaining balance in response headers. Add `-i` to any example to inspect them: ```bash curl -i -H "Authorization: Bearer $SEMANTIL_API_KEY" \ "https://semantil.com/api/me" ``` Use the [usage guide](/credits/) for request caps and charging behavior, and the [API reference](/api-reference/) for the complete contract. --- # Quickstart > Get a first Semantil result through the browser or REST API. Semantil finds companies, enriches domains, and discovers lookalikes. Choose the shortest way to get your first result.
Open Playground ↗ View API reference
## Choose an API Start from what you already know. The Playground exposes the same three core actions without requiring you to build the request by hand. | You have | Use | What it does | | --- | --- | --- | | A company domain | **Domain enrichment** | Returns selected profile, technology, company, contact, commerce, or merchant-size data for that domain. | | A description of a market | **Company search** | Finds companies using business-language search and verified catalog filters. | | A strong customer or competitor | **Lookalike** | Uses one seed domain to return a ranked list of similar companies. | See [copy-ready examples](/examples/) for each action, or open the [API reference](/api-reference/) for every parameter and response schema. ## Make your first API call 1. **Create an API key** Open [API keys](https://semantil.com/api#api-keys) and create one key for this integration. 2. **Verify the key** ```bash curl -H "Authorization: Bearer $SEMANTIL_API_KEY" \ "https://semantil.com/api/me" ``` A `200` response means the key is ready. This authentication check does not consume credits. 3. **Enrich one domain** ```bash curl -H "Authorization: Bearer $SEMANTIL_API_KEY" \ "https://semantil.com/api/domains/notino.pl?products=profile" ``` This asks for the `profile` product. Check the live [`GET /api/products`](https://semantil.com/api/products) catalog for current products and usage units before setting a request budget. Give it the [OpenAPI contract](/openapi.yaml) or the compact [`llms.txt`](/llms.txt) index. Both are generated from the current public documentation. ## Next - [Examples](/examples/) — copy practical enrichment, search, and lookalike requests. - [Authentication](/authentication/) — create and protect integration keys. - [API reference](/api-reference) — inspect endpoints and test requests. - [Usage and credits](/credits/) — read live usage data and cap requests. - [Errors](/errors/) — handle stable error codes.