Integrating Karla AI Search via API

This guide shows how to test the Karla Search API in the API documentation and then use the same requests in your own frontend integration. The goal is a search interface, inline or popup, with AI answers and relevant sources.

Start in the API documentation. Here you will find endpoints, request bodies, response formats and error responses. In the API, an agent is identified by the field model_id. In the examples, MODEL_ID is a placeholder that you should replace with the ID of your own agent.

Create OAuth 2.0 credentials

Log in to the Karla platform, go to Karla's developer settings, and create a set of OAuth 2.0 credentials. Store your client_id and client_secret in a secure place. The credentials must belong to the organization the agent belongs to.

Keep the secret in your backend

In your own integration, the client_secret must be stored in the backend and must never be included in the frontend code.

Log in to the API documentation and authorize first

Open the API documentation and log in if prompted.
Enter the Client ID and Client Secret from step 1 in the fields at the top, and click Authorize.
Wait until the documentation shows ✓ Authorized before testing endpoints with Try it out and Execute.

Authorize before your first API call

Logging in to Karla does not replace authorization of API requests. Without a valid access token, the protected calls will fail. The documentation fetches the token and automatically adds Authorization: Bearer <access_token> to your requests.

Retrieve the published version of your agent

Choose the search agent you want to integrate with and use its model ID. The agent must belong to your organization and have a published version. Contact Karla if you are missing the agent's ID.

Find GET /v1/models/{model_id}/published under Models. Click Try it out, enter your agent's ID as model_id, and click Execute.

HTTP

GET https://api.getkarla.ai/v1/models/{model_id}/published
Authorization: Bearer <access_token>

On success, the response contains type: "success" and the published search agent's configuration under response. The relevant fields are:

Field in the response

Usage

response.id

The agent's model ID. Used as model_id in the search call.

response.version_id

The ID of the published version. Can be sent as model_version_id if you want to select this version explicitly.

response.metadata and response.styles

Configuration you can use for texts and styling in your UI as needed.

You do not need to specify a version in the first search call: without model_version_id, the API uses the agent's currently published version.

Send a search

Find POST /v1/search/query under Search, and click Try it out. Use the following request body with your OAuth credentials, and replace MODEL_ID with the same agent ID as in step 3:

JSON

{
  "model_id": "MODEL_ID",
  "message": {
    "role": "user",
    "content": "Write your search query here"
  },
  "stream": false,
  "conversation_id": null
}

For OAuth calls, the fields must be placed directly in the JSON object. Use Content-Type: application/json. The example uses stream: false so you can read the complete response directly in the documentation without setting up a socket connection.

Click Execute and check the response:

type is "success" for a completed call.
response.messages contains the messages. Display content from messages with role: "assistant" as the AI answer.
response.search_query_hits contains the search results. Use title and, where available, url for the source list.
response.id is the conversation ID. Send it as conversation_id for a follow-up question. Use null for a new conversation.

See the endpoint's schema and examples in the API documentation for other fields and possible error responses.

Transfer the calls to your code and build the UI

Once the model and search calls work in the documentation, you can use exactly the same URLs, headers and request bodies in your own integration. Optionally, copy the cURL request generated by the documentation as a starting point.

Backend: credentials and access token

Let your backend fetch and store the access token and forward model and search calls to the Karla API. The frontend calls your backend, which adds the Bearer token.

The token is fetched with the following request. Replace the placeholders with your credentials, and send the body as URL-encoded form data:

HTTP

POST https://api.getkarla.ai/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>

Read access_token and expires_in from the token response. The current API implementation issues OAuth tokens with a lifetime of 3600 seconds. Reuse the token while it is valid, and fetch a new one with the same client credentials call when it expires. This flow does not issue a refresh token.

Frontend: answers and sources

Build a responsive search field, inline or popup.
Show a clear loading state while the search is running, and an understandable error message if the call fails.
Display the AI answer with Markdown support, including headings, lists and bold text.
Show sources with a title and a link to the original source when a link is available.
Store the conversation ID if the user should be able to ask follow-up questions. Optionally add suggested questions as buttons.

Streaming with Socket.IOOptional

Once the regular request works, you can add progressive display of the answer. Connect via Socket.IO to the namespace /v1/search/query, join a unique room with join_room, and send the same room in the search request together with stream: true.

Event

Usage

receive_message

Receive message creation and incremental text chunks for the AI answer.

receive_conversation_id

Store the conversation ID for follow-up questions.

search_query_hits

Update the source list with the search results.

finished_text_generation

Mark that answer generation is complete.

If a call fails

First check that the documentation shows Authorized, that your credentials belong to the correct organization, and that the agent has a published version. Then check the request body against the endpoint's schema, and read the HTTP status and the error message in the response.

Finally, let us know if you run into anything along the way, and we will help you move forward.