Skip to main content

Integration Getting Started

API version: v1 Estimated reading time: 12 minutes Audience: Integrators and backend developers

This guide walks you through building your first integration with the Booga Enterprise API. By the end, you will have an API key, made your first authenticated requests, and understand the patterns for common operations like listing resources, uploading files, and triggering agent workflows.

Prerequisites​

Before you begin, ensure you have:

  • A Booga Enterprise account on a corporate tenant with API Management enabled
  • The API_MANAGEMENT_WRITE permission to create API keys
  • An HTTP client such as cURL, Postman, or a programming language with an HTTP library
  • The API base URL for your environment (e.g., https://api.boogaenterprise.com for production)

Step 1: Create an API Key​

  1. Log in to the Booga Enterprise dashboard
  2. Open API Management from the sidebar
  3. Go to the API Keys tab and click Create API Key
  4. Name the key descriptively (e.g., "My First Integration")
  5. Select the scopes you need — for this tutorial, select FILES_READ, FILES_WRITE, and CHAT_READ
  6. Leave rate limits at defaults (60/min, 3,600/hour)
  7. Click Create
  8. Copy the key immediately — it is shown only once

Store the key in an environment variable:

export BOOGA_API_KEY="bge_your_key_here"

Step 2: Verify Your Key​

Test that your key works by calling the health endpoint:

curl -s https://api.boogaenterprise.com/api/health/ \
  | python -m json.tool

Then try an authenticated endpoint — list your files:

curl -s -H "Authorization: Bearer $BOOGA_API_KEY" \
  https://api.boogaenterprise.com/api/files/ \
  | python -m json.tool

You should receive a JSON response with count, results, next, and previous fields. If you get a 401 response, double-check that the key is active and correctly formatted in the header.

Step 3: List Resources​

Most list endpoints follow the same pagination pattern. Here are examples for common resources:

List Files​

curl -s -H "Authorization: Bearer $BOOGA_API_KEY" \
  "https://api.boogaenterprise.com/api/files/?limit=10&offset=0"

List Chat Sessions​

curl -s -H "Authorization: Bearer $BOOGA_API_KEY" \
  "https://api.boogaenterprise.com/api/chat/sessions/?limit=10"

List Agents​

curl -s -H "Authorization: Bearer $BOOGA_API_KEY" \
  "https://api.boogaenterprise.com/api/agents/?limit=10"

Each response uses the standard envelope:

{
  "count": 25,
  "next": "https://api.boogaenterprise.com/api/files/?limit=10&offset=10",
  "previous": null,
  "results": [ ... ]
}

Step 4: Upload a File​

Upload a file using a multipart form request:

curl -X POST \
  -H "Authorization: Bearer $BOOGA_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "name=Quarterly Report" \
  https://api.boogaenterprise.com/api/files/upload/

The response includes the newly created file object with its id, which you can use in subsequent requests:

{
  "id": "f8c1d2e3-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "name": "Quarterly Report",
  "original_filename": "document.pdf",
  "size": 1048576,
  "content_type": "application/pdf",
  "status": "processing",
  "created_at": "2026-03-30T14:25:00Z"
}

Note: Large file uploads trigger asynchronous processing (text extraction, embedding generation). The file status transitions from processing to ready when complete. Poll the file detail endpoint or use webhooks to be notified.

Step 5: Search the Knowledge Base​

If your tenant has a knowledge base populated with documents, you can search it programmatically:

curl -s -H "Authorization: Bearer $BOOGA_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"query": "revenue growth Q4 2025", "limit": 5}' \
  https://api.boogaenterprise.com/api/knowledge/search/

The response returns semantically relevant results ranked by relevance score.

Step 6: Create a Chat Session​

Start an AI chat session and send a message:

# Create a session
curl -s -X POST \
  -H "Authorization: Bearer $BOOGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "API Test Session"}' \
  https://api.boogaenterprise.com/api/chat/sessions/

Save the returned session_id, then send a message:

curl -s -X POST \
  -H "Authorization: Bearer $BOOGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize the key findings from our Q4 report.", "session_id": "<session_id>"}' \
  https://api.boogaenterprise.com/api/chat/messages/

The AI response is returned in the response body. For streaming responses, use the streaming endpoint variant (see the API reference for details).

Step 7: Trigger an Agent Workflow​

If you have agents configured, trigger an execution:

curl -s -X POST \
  -H "Authorization: Bearer $BOOGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "Generate a market analysis for AAPL"}}' \
  https://api.boogaenterprise.com/api/agents/<agent_id>/execute/

Agent executions are asynchronous. The response returns an execution ID and status. Poll the execution detail endpoint to check progress, or configure a webhook to receive completion notifications.

Using Generated SDKs​

Instead of making raw HTTP requests, you can generate a typed client SDK from the API Management console:

Python SDK​

from booga_enterprise import BoogaClient

client = BoogaClient(
    base_url="https://api.boogaenterprise.com",
    api_key="bge_your_key_here"
)

# List files
files = client.files.list(limit=10)
for f in files.results:
    print(f"{f.name} ({f.size} bytes)")

# Upload a file
with open("report.pdf", "rb") as fp:
    new_file = client.files.upload(file=fp, name="Q4 Report")
    print(f"Uploaded: {new_file.id}")

TypeScript SDK​

import { BoogaClient } from 'booga-enterprise-sdk';

const client = new BoogaClient({
  baseUrl: 'https://api.boogaenterprise.com',
  apiKey: 'bge_your_key_here',
});

const files = await client.files.list({ limit: 10 });
files.results.forEach(f => console.log(`${f.name} (${f.size} bytes)`));

Download SDKs from the API Explorer tab in API Management, or call GET /api/api-management/generate-sdk/?language=python&download=zip.

Integration with External Connectors​

Beyond direct API calls, the Integrations plugin supports pre-built connectors for external services. If your workflow involves pulling data from or pushing data to cloud services (Salesforce, Slack, OneDrive, Google Drive, etc.), consider using the connector framework:

  1. Configure a connection in the Integrations plugin with the external service's credentials
  2. Set up a sync pipeline to automate data flow between Booga Enterprise and the external system
  3. Use webhooks to trigger actions when events occur in either system

For detail on connector types, OAuth flows, and sync configuration, see the Integrations — User Guide.

Handling Errors​

Implement robust error handling in your integration:

import requests

response = requests.get(
    "https://api.boogaenterprise.com/api/files/",
    headers={"Authorization": f"Bearer {api_key}"}
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 401:
    # Key is invalid, expired, or revoked — re-authenticate
    raise AuthenticationError("API key is not valid")
elif response.status_code == 403:
    # Missing required scope or IP blocked
    error = response.json()
    raise PermissionError(f"Forbidden: {error.get('detail')}")
elif response.status_code == 429:
    # Rate limited — back off and retry
    import time
    time.sleep(10)
    # Retry the request
else:
    response.raise_for_status()

Next Steps​

Now that you have a working integration, explore these topics:

⏱️ Read time: 12 minutes | 📊 Difficulty: beginner