Quick Start Guide

Get up and running with the Ontbo API in 5 minutes

Using Python? Make it even easier with our Python client library

1

Get Your API Key

First, you'll need to create an account and get your API key. This key will be used to authenticate all your requests.

2

Create a Profile

A profile represents one of your users, you will use them to send conversational content and make queries.

curl
curl -X POST "https://api.ontbo.com/api/tests/profiles?requested_id=my_user" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "id": "my_user"
}

Note: Since profile IDs must be unique, the actual profile ID is returned by the system in the HTTP reply.

3

Create a Scene

A scene represents a chat between the user and the system.

curl
curl -X POST "https://api.ontbo.com/api/tests/profiles/my_user/scenes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "id": "new_scene"
}

Note: Since scene IDs must be unique, the actual scene ID is returned by the system in the HTTP reply.

4

Add Some Data to the Scene

Now let's add some conversational data to the scene. This will be processed to extract facts about the user.

curl
curl -X POST "https://api.ontbo.com/api/tests/profiles/my_user/scenes/new_scene/text?update_now=true&wait_for_result=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "role": "user",
      "content": "Hi! I love cycling, any suggestion of nice spots near Paris?",
      "timestamp": 1731964920
    },
    {
      "role": "assistant", 
      "content": "Here are some great cycling spots near Paris: Bois de Vincennes or Bois de Boulogne for leafy short rides, the La Seine à Vélo route to cycle from Paris toward the sea, the Avenue Verte (London–Paris greenway), or loops through the Parc Naturel Régional de la Haute Vallée de Chevreuse.",
      "timestamp": 1731964925
    }
  ]'

Response:

{
  "id": "2"
}
5

Query the Profile

Now we can query the profile to include the relevant information about the user:

curl
curl -X GET "https://api.ontbo.com/api/tests/profiles/my_user/facts/query?query=What sports does the user enjoy?" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "result": "The user enjoys cycling."
}

That's all! You've successfully created a profile, added conversational data, and queried it for relevant information.

Common Issues

401 Unauthorized

Make sure your API key is correct and included in the Authorization header as Bearer YOUR_API_KEY.

What's Next?

You're all set! Here are some recommended next steps to continue building with our API:

→ Explore the interactive API documentation→ Use our Python client library for easier integration→ Learn about core concepts like retrieval modes and update policies