T
testing
Advanced Features & Technical Guides Managing Search Operations via API

Integrate powerful search capabilities directly into your own applications, portals, or custom interfaces using the GitDocAI Search API. This guide covers how to programmatically query your documentation's search index to deliver fast, relevant results to your users.

Before you begin, ensure you have your API credentials, your organization_id, and the documentation_id for the project you want to query.


If you are building a frontend application, never expose your primary API keys in the client code. Always route search requests through your own backend server to keep your credentials secure.

How the Search Flow Works

When you query the Search API, it scans the most recently published version of your documentation. Here is a typical implementation flow:

sequenceDiagram
    participant User
    participant App as "Your Application"
    participant API as "GitDocAI API"
    
    User->>App: Types search query (e.g., "authentication")
    App->>API: POST /documentations/{org_id}/{doc_id}/search
    API-->>App: Returns matched headings and snippets
    App-->>User: Displays formatted search results

Implementing the Search Request

To perform a search, you will use the dedicated search endpoint.

MethodEndpointDescription
POST/documentations/{organization_id}/{documentation_id}/searchQueries the search index for a specific documentation project.
  1. 1

    Prepare your request

    Construct your API call using your organization and documentation IDs. You will need to pass your search parameters (like the user's query string) in the JSON body of the request.

  2. 2

    Execute the search

    Make the POST request to the endpoint. Here is an example using curl:

    curl -X POST https://api.gitdocai.com/documentations/org_123/doc_456/search 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"query": "getting started", "limit": 10}'
  3. 3

    Process the results

    The API will return a JSON array containing the most relevant documentation sections, including titles, URLs, and text snippets highlighting the matched keywords. Map these results to your custom UI.

Keeping Your Search Index Updated

Your search index is directly tied to your published documentation. Whenever you make changes to your content, the search index is automatically rebuilt during the publishing process.

If your search results seem outdated, you may need to trigger a new publish job.


The search index is only updated upon a successful publish. Draft changes will not appear in the Search API results.

You can programmatically manage the publishing lifecycle to ensure your search index is always fresh:

ActionEndpointMethod
Start Publish/documentations/{documentation_id}/publishPOST
Check Status/documentations/{documentation_id}/publish/statusGET
Get Latest/documentations/{documentation_id}/publish/latestGET
Get History/documentations/{documentation_id}/publish/historyGET
How do I know when the search index is ready?

When you trigger a publish job using the POST /publish endpoint, the indexing happens asynchronously. You can poll the GET /publish/status endpoint. Once the status returns as completed, your new search index is fully active and ready to be queried.

Can I search across multiple documentation projects at once?

Currently, the search endpoint is scoped to a single documentation_id. To search across multiple projects, you will need to make parallel requests to the search endpoint for each respective documentation ID and merge the results in your application.

Next Steps

Event Webhooks

Learn how to use the Events API to listen for publish completions and automatically trigger your application's cache invalidation.