> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intellibase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggest Ontology

> Get an AI-generated ontology suggestion by describing the use case or agent persona, optionally sample expected input/ ouput that the agent will be expected to perform.

## Endpoint

```
POST https://api.intellibase.dev/api/v1/ontologies/suggest
```

## Authentication

Requires a valid API key.

## Request Body

<ParamField body="usecase" type="string" required>
  Description of your use case or domain. Be specific about the entities, relationships, and concepts you want to track.
</ParamField>

## Response

Returns an ontology specification in the same format as the [Create Ontology](/api-reference/ontologies/create) request body.

<ResponseField name="name" type="string">
  AI-generated name for the ontology
</ResponseField>

<ResponseField name="schema" type="object">
  Complete ontology schema ready to be used in [Create Ontology](/api-reference/ontologies/create)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.intellibase.dev/api/v1/ontologies/suggest \
    -H "Authorization: Bearer ib-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "usecase": "Track customer support tickets, agents, customers, and resolutions. Include ticket categories, priority levels, and customer satisfaction ratings."
    }'
  ```

  ```python Python theme={null}
  import requests

  usecase = """
  Track customer support tickets, agents, customers, and resolutions.
  Include ticket categories, priority levels, and customer satisfaction ratings.
  """

  response = requests.post(
      "https://api.intellibase.dev/api/v1/ontologies/suggest",
      headers={
          "Authorization": "Bearer ib-your-api-key",
          "Content-Type": "application/json"
      },
      json={"usecase": usecase}
  )

  suggested_ontology = response.json()

  # Review the suggestion
  print(f"Suggested ontology: {suggested_ontology['name']}")
  print(f"Node types at Level 0:")
  for node_type in suggested_ontology['schema']['ontology']['hierarchy'][0]['node_types'].keys():
      print(f"  - {node_type}")

  # If satisfied, create it
  create_response = requests.post(
      "https://api.intellibase.dev/api/v1/ontologies",
      headers={
          "Authorization": "Bearer ib-your-api-key",
          "Content-Type": "application/json"
      },
      json=suggested_ontology
  )

  ontology = create_response.json()
  print(f"Created ontology: {ontology['id']}")
  ```

  ```typescript TypeScript theme={null}
  const usecase = `
  Track customer support tickets, agents, customers, and resolutions.
  Include ticket categories, priority levels, and customer satisfaction ratings.
  `;

  const response = await fetch(
    "https://api.intellibase.dev/api/v1/ontologies/suggest",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer ib-your-api-key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ usecase })
    }
  );

  const suggestedOntology = await response.json();

  // Review the suggestion
  console.log(`Suggested ontology: ${suggestedOntology.name}`);
  const level0Types = suggestedOntology.schema.ontology.hierarchy[0].node_types;
  console.log("Node types at Level 0:");
  Object.keys(level0Types).forEach(type => console.log(`  - ${type}`));

  // If satisfied, create it
  const createResponse = await fetch(
    "https://api.intellibase.dev/api/v1/ontologies",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer ib-your-api-key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(suggestedOntology)
    }
  );

  const ontology = await createResponse.json();
  console.log(`Created ontology: ${ontology.id}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "name": "Customer Support Ontology",
    "schema": {
      "ontology": {
        "hierarchy": [
          {
            "level": 0,
            "node_types": {
              "Ticket": {
                "properties": ["title", "priority", "status", "satisfaction_rating"],
                "description": "Customer support ticket"
              },
              "Agent": {
                "properties": ["name", "specialization", "active"],
                "description": "Support agent"
              },
              "Customer": {
                "properties": ["name", "tier", "email"],
                "description": "Customer who filed ticket"
              }
            }
          },
          {
            "level": 1,
            "node_types": {
              "Category": {
                "aggregates": ["Ticket"],
                "properties": ["name", "description"],
                "description": "Ticket category or topic area"
              }
            }
          }
        ],
        "edge_types": [
          {
            "name": "ASSIGNED_TO",
            "source_types": ["Ticket"],
            "target_types": ["Agent"],
            "properties": ["assigned_date"],
            "temporal": true,
            "description": "Ticket assigned to agent"
          },
          {
            "name": "FILED_BY",
            "source_types": ["Ticket"],
            "target_types": ["Customer"],
            "properties": [],
            "temporal": false,
            "description": "Ticket filed by customer"
          },
          {
            "name": "BELONGS_TO_CATEGORY",
            "source_types": ["Ticket"],
            "target_types": ["Category"],
            "properties": [],
            "temporal": false,
            "description": "Ticket categorization"
          }
        ]
      }
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": "Use case description is required"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "detail": "Failed to generate ontology suggestion: LLM service unavailable"
  }
  ```
</ResponseExample>

<Info>
  **Review before creating!** The AI-generated ontology is a starting point. Review and modify it to match your specific needs before creating it.
</Info>

<Tip>
  **Be specific in your use case description** for better results:

  * ✅ Good: "Track software projects, developers, features, and deadlines. Include team hierarchies and feature dependencies."
  * ❌ Too vague: "Track my work stuff"
</Tip>

<Warning>
  The suggestion endpoint uses LLM calls and may take around 30 seconds to complete.
</Warning>