Skip to main content

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.
The Indexing API authenticates with a service-account API key sent as a Bearer token:
User tokens and personal API keys are not accepted on these endpoints --- only service-account tokens.

Create a service account

  1. In amber, open Company settings → API Access.
  2. In the Indexing API section, click Create Service Account.
  3. 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.
  4. Copy the API Token from the confirmation dialog.
Each token begins with the 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.
The service-account list shows each key’s prefix, creation date, last used date, and expiry, so you can identify which key an integration is using. You can edit a service account’s name and description later. The expiry date is fixed at creation: to rotate or extend a key, create a new service account, switch your integration over, then delete the old one. Deleting a service account invalidates its token immediately --- any integration still using it receives 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.email to that exact login email.
  • In permissions and group memberships, refer to people by that email (allowed_users, member_email for memberships, and checks that take user_email).
Do not rely on arbitrary external IDs alone to represent “who is logged in”; amber resolves search visibility using the email tied to the amber user.

Naming rules at a glance

A few identifiers must be slugs in word_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)
Group names cannot contain spaces and cannot start with 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:
2. Index a document:
The same endpoint accepts an array under 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.
  1. Datasource & custom properties --- create the datasource, sub-datasource tree, object types, and property definitions.
  2. Index documents --- push and update documents (single or bulk), bodies, and per-document permissions.
  3. 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.