Getting Started

Welcome to Intentgine! This guide will walk you through creating an account, generating an API key, and making your first intent resolution request.

1. Create an Account

To use Intentgine, you need an account.

1. Visit the Developer Console.
2. Sign up with your email and password.
3. You will be automatically assigned to a default Team.

2. Generate an API Key

Once logged in:

1. Navigate to the Apps section.
2. Click Create New App.
3. Give your app a name (e.g., “My First App”).
4. Copy the generated API Key immediately. You won’t be able to see it again!

Caution

Your API Key starts with sk_live_. Keep it secure. Do not commit it to public repositories.

3. Authenticate

Before making API calls, exchange your API key for a short-lived JWT token:

cURL

curl -X POST https://api.intentgine.dev/v1/auth \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

TypeScript

const auth = await fetch('https://api.intentgine.dev/v1/auth', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_live_YOUR_API_KEY' }
});
const { token } = await auth.json();

Python

import requests

auth = requests.post('https://api.intentgine.dev/v1/auth',
  headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"})
token = auth.json()["token"]

Save the returned token — you’ll use it for all subsequent requests. Tokens expire after 1 hour. See Authentication for details.

4. Make Your First Request

Now you’re ready to resolve an intent. We’ll use the /v1/resolve-quick endpoint to map a natural language query to a tool.

This endpoint accepts inline tool definitions, making it perfect for getting started. In this example, we define a simple tool get_weather and ask “What’s the weather in London?“.

cURL

curl -X POST https://api.intentgine.dev/v1/resolve-quick \
  -H "Authorization: Bearer <YOUR_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the weather in London?",
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location"]
        }
      }
    ]
  }'

HTTPie

http POST https://api.intentgine.dev/v1/resolve-quick \
  Authorization:"Bearer <YOUR_JWT_TOKEN>" \
  query="What is the weather in London?" \
  tools:='[{"name":"get_weather","description":"Get current weather for a location","parameters":{"type":"object","properties":{"location":{"type":"string"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}]'

TypeScript

const response = await fetch('https://api.intentgine.dev/v1/resolve-quick', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "What is the weather in London?",
    tools: [
      {
        name: "get_weather",
        description: "Get current weather for a location",
        parameters: {
          type: "object",
          properties: {
            location: { type: "string" },
            unit: { type: "string", enum: ["celsius", "fahrenheit"] }
          },
          required: ["location"]
        }
      }
    ]
  })
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.intentgine.dev/v1/resolve-quick"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}
payload = {
    "query": "What is the weather in London?",
    "tools": [
        {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location"]
            }
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
)

func main() {
  url := "https://api.intentgine.dev/v1/resolve-quick"
  payload := []byte(`{
    "query": "What is the weather in London?",
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location"]
        }
      }
    ]
  }`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
  req.Header.Set("Authorization", "Bearer <YOUR_JWT_TOKEN>")
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  var result map[string]interface{}
  json.NewDecoder(resp.Body).Decode(&result)
  fmt.Println(result)
}

5. Understand the Response

You should receive a JSON response similar to this:

{
  "resolved": {
    "tool": "get_weather",
    "parameters": {
      "location": "London",
      "unit": "celsius"
    }
  },
  "metadata": {
    "source": "compute",
    "used_banks": [],
    "latency_ms": 450,
    "requests_used": 1
  }
}

• resolved: Contains the selected tool and extracted parameters.
• metadata.source: compute means processing was required; cache means it came from semantic cache.
• metadata.requests_used: The number of requests consumed by this call (always 1 for single resolve).

Tip

The /v1/resolve-quick endpoint is great for prototyping, but doesn’t benefit from semantic caching. For production use, create toolsets and use /v1/resolve with toolset signatures for better performance and caching. Learn more in the Toolsets concept guide.

Next Steps

• Explore Core Concepts
• Learn about Memory Banks
• Check the API Reference