Overview
The amber Indexing API enables your organization to push content from internal tools, on-premises systems, and proprietary applications into amber’s search index. Documents pushed through this API become discoverable alongside content from all your natively connected data sources.The Indexing API is designed for a push-based integration model. Instead of amber pulling data from your system, your application pushes documents (one at a time or in batches) directly to amber via HTTP API calls.
The public
/api/indexing endpoints are a thin gateway in front of amber’s internal indexing service. The gateway authenticates your service account, applies rate limits, and validates the request body; the request is then forwarded to the indexing service, which performs the actual extraction and indexing work. Status codes and error bodies from the indexing service are passed through unchanged. Errors raised by the gateway itself (authentication, rate limiting, request validation, connectivity) use a slightly different envelope --- see Common HTTP responses.Browse this guide
Use the cards below (or the recommended order at the end) to move between topics.Overview
This page --- API overview, auth, quick examples
Datasource & custom properties
Create datasource, sub-datasources, object types, property schemas
Index documents
Single + bulk indexing, fields, update, delete, error handling
Permissions
Users, groups, anonymous access, check-access
Common Use Cases
- Internal Tool Integration --- Make content from proprietary or on-premises tools searchable in amber.
- Legacy System Modernization --- Bring content from older systems into modern search and AI workflows.
- Custom Application Data --- Index structured data from internal applications and databases.
- Document Repositories --- Make file servers, wikis, and document management systems searchable.
- Ticketing & CRM Data --- Push tickets, cases, and customer data for unified search.
How It Works
1
Create a datasource (with subs and property schemas)
Register the datasource and declare object types, custom property definitions, and the optional sub-datasource hierarchy in one call. See Datasource & custom properties.
2
Index content
Push documents with
POST /documents --- send a single document or an array under documents. For each one you choose between file binaries (server-side extraction) and clean text_content you supply yourself. Updates and deletes use the same endpoint family. See Index documents.3
Configure permissions
Set access controls so users only see content they are authorized to view. Documents without an explicit
permissions block are treated as anonymous and visible to everyone registered on that datasource (POST /users) --- not to your whole org. A user with no record on the datasource sees none of its documents. See Permissions.4
Search & discover
Documents become discoverable through amber’s search and AI features once the server commits them to the index. This is controlled server-side and can take up to 2 hours.
Base URL
All Indexing API endpoints are available under:Authentication
You need the Administrator role in amber to create an indexing service account. No request to the amber team is necessary --- service accounts are fully self-service.
Create a service account
- In amber, open Company settings → API Access.
- In the Indexing API section, click Create Service Account.
- Enter a Name (must be unique), an optional Description (e.g. owner team or what the key is for), and an optional Expires On date. With an expiry date, the token stops working at the end of that day (UTC); leave it empty for a token that never expires.
- Copy the API Token from the confirmation dialog.
amsa_ prefix so leaked credentials are easy to spot in logs. The token is shown only once at creation time and cannot be recovered later --- store it in your secret manager immediately, then use it in place of YOUR_API_KEY in the examples on these pages.

401 Unauthorized.
A service account belongs to your organization. Datasources, users, and groups created through the Indexing API are scoped to your organization and are shared by all of its service accounts.
Linking people who search to your indexed data
Who can see a document in amber is evaluated against the same person who signs in to amber. The required way to connect that logged-in identity to the Indexing API is the user’s email attribute --- the email on their amber account (as provided by your identity provider / directory and stored on the user in amber).- When you index users, set
user.emailto that exact login email. - In permissions and group memberships, refer to people by that email (
allowed_users,member_emailfor memberships, and checks that takeuser_email).
Naming rules at a glance
A few identifiers must be slugs inword_word form (lowercase letters/digits separated by single underscores --- no hyphens, no spaces, no leading digit):
- Datasource
name(e.g.internal_wiki) --- unique within your organization - Sub
key(e.g.engineering,runbooks)
amber (case-insensitive). Document ids may contain letters, digits, hyphens, underscores, and dots (max 512 characters), but not two of the same separator in a row (--, __, ..).
Quick Example
Here’s how to create a datasource and index your first document: 1. Create a datasource:documents for bulk indexing — a separate bulk route is not needed. See Index documents.
Common HTTP responses
These responses can come back from any endpoint and are not repeated in the per-endpoint tables on the other pages.
Errors returned by the indexing service itself (for example
404 datasource not found, 409 conflicts, and custom-property / sub-reference schema violations with an error_code) use a different envelope: {"status": "error", "details": ...} — see Schema validation & errors on the Index documents page.
Limits & timing
Rate limits are applied per service account (not per IP or per server), so spreading requests over several clients that share one token does not raise the quota.
When a limit is exceeded the API answers 429 Too Many Requests with a
Retry-After header (seconds). For POST /documents, a request that would push the running total over the quota is rejected as a whole --- none of its documents are indexed --- so a single bulk request with more documents than the per-minute quota (500 by default) can never succeed. Split large imports into smaller batches.
Oversized binary_base64 payloads are rejected with 422 before they reach the indexing pipeline (binary_base64 decodes to ~… MB which exceeds the 100 MB per-document limit.).
If connecting to, sending to, or reading from the indexing service takes longer than 30 seconds, the request fails with 502 Bad Gateway. Keep bulk batches (especially ones with file binaries) small enough to finish within that window.
The two rate limits and the binary size cap can be configured per deployment --- contact amber if you need different values. The 30-second timeout is fixed.
Indexed content is not immediately searchable. The server commits new data to the search index on its own schedule, which can take up to 2 hours.
Recommended reading order
- Datasource & custom properties --- create the datasource, sub-datasource tree, object types, and property definitions.
- Index documents --- push and update documents (single or bulk), bodies, and per-document permissions.
- Permissions --- users, groups, memberships, and access checks.
Next Steps
Datasource & custom properties
Datasource, sub-datasources, object definitions, property schemas, and sending values on documents.
Index Documents
Index, update, and delete documents (single or bulk).
Permissions
Configure fine-grained access controls for your indexed documents.