API Reference

This reference documents the endpoints available in the Tiptree Platform API. The API follows RESTful principles and uses JSON for request and response bodies.

Base URL

https://api.tiptreesystems.com

For self-hosted deployments, use your custom domain.

API Versioning

The API is versioned through the URL path. Currently, two versions are supported:

/v1 - Basic messaging API
/v2 - Full agent management API

Authentication

All API requests require authentication. See the Authentication guide for details.

V1 API Endpoints

Messages

List Messages

GET /v1/messages

Retrieves a list of messages for a user.

Query Parameters:

Parameter	Type	Description
`user_id`	string	The ID of the user
`limit`	integer	Maximum number of messages to return (default: 50)
`offset`	integer	Number of messages to skip (default: 0)

Response:

{
  "messages": [
    {
      "id": "msg_123",
      "content": "Hello, world!",
      "timestamp": "2023-01-01T00:00:00Z",
      "read": true
    },
    ...
  ],
  "total": 100
}

Send Message

POST /v1/messages/send

Sends a message to a user.

Request Body:

{
  "user_id": "user_123",
  "content": "Hello, world!"
}

Response:

{
  "id": "msg_456",
  "timestamp": "2023-01-01T00:00:00Z"
}

Mark Message as Read

PUT /v1/messages/{message_id}/read

Marks a message as read.

Response:

{
  "id": "msg_123",
  "read": true
}

V2 API Endpoints

Agents

List Agents

GET /v2/agents

Retrieves a list of agents.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Maximum number of agents to return (default: 50)
`offset`	integer	Number of agents to skip (default: 0)

Response:

{
  "agents": [
    {
      "id": "agent_123",
      "name": "My Agent",
      "description": "A helpful assistant",
      "model": "gpt-4",
      "created_at": "2023-01-01T00:00:00Z"
    },
    ...
  ],
  "total": 10
}

Create Agent

POST /v2/agents

Creates a new agent.

Request Body:

{
  "name": "My Agent",
  "description": "A helpful assistant",
  "model": "gpt-4",
  "system_prompt": "You are a helpful assistant.",
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

Response:

{
  "id": "agent_123",
  "name": "My Agent",
  "description": "A helpful assistant",
  "model": "gpt-4",
  "system_prompt": "You are a helpful assistant.",
  "tools": [...],
  "created_at": "2023-01-01T00:00:00Z"
}

Get Agent

GET /v2/agents/{agent_id}

Retrieves an agent by ID.

Response:

{
  "id": "agent_123",
  "name": "My Agent",
  "description": "A helpful assistant",
  "model": "gpt-4",
  "system_prompt": "You are a helpful assistant.",
  "tools": [...],
  "created_at": "2023-01-01T00:00:00Z"
}

Update Agent

PUT /v2/agents/{agent_id}

Updates an agent.

Request Body:

{
  "name": "Updated Agent Name",
  "description": "An updated description",
  "system_prompt": "You are an updated assistant."
}

Response:

{
  "id": "agent_123",
  "name": "Updated Agent Name",
  "description": "An updated description",
  "model": "gpt-4",
  "system_prompt": "You are an updated assistant.",
  "tools": [...],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-02T00:00:00Z"
}

Delete Agent

DELETE /v2/agents/{agent_id}

Deletes an agent.

Response:

{
  "success": true
}

Sessions

List Sessions

GET /v2/sessions

Retrieves a list of sessions.

Query Parameters:

Parameter	Type	Description
`agent_id`	string	Filter sessions by agent ID
`limit`	integer	Maximum number of sessions to return (default: 50)
`offset`	integer	Number of sessions to skip (default: 0)

Response:

{
  "sessions": [
    {
      "id": "session_123",
      "agent_id": "agent_123",
      "created_at": "2023-01-01T00:00:00Z",
      "last_active_at": "2023-01-01T01:00:00Z"
    },
    ...
  ],
  "total": 5
}

Create Session

POST /v2/sessions

Creates a new session.

Request Body:

{
  "agent_id": "agent_123",
  "metadata": {
    "user_id": "user_456",
    "source": "web"
  }
}

Response:

{
  "id": "session_123",
  "agent_id": "agent_123",
  "metadata": {
    "user_id": "user_456",
    "source": "web"
  },
  "created_at": "2023-01-01T00:00:00Z"
}

Get Session

GET /v2/sessions/{session_id}

Retrieves a session by ID.

Response:

{
  "id": "session_123",
  "agent_id": "agent_123",
  "metadata": {
    "user_id": "user_456",
    "source": "web"
  },
  "created_at": "2023-01-01T00:00:00Z",
  "last_active_at": "2023-01-01T01:00:00Z"
}

Delete Session

DELETE /v2/sessions/{session_id}

Deletes a session.

Response:

{
  "success": true
}

Messages

List Messages

GET /v2/sessions/{session_id}/messages

Retrieves messages for a session.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Maximum number of messages to return (default: 50)
`before`	string	Return messages before this message ID

Response:

{
  "messages": [
    {
      "id": "msg_123",
      "session_id": "session_123",
      "role": "user",
      "content": "Hello, world!",
      "created_at": "2023-01-01T00:00:00Z"
    },
    {
      "id": "msg_124",
      "session_id": "session_123",
      "role": "assistant",
      "content": "Hello! How can I help you today?",
      "created_at": "2023-01-01T00:00:01Z"
    },
    ...
  ]
}

Send Message

POST /v2/sessions/{session_id}/messages

Sends a message to a session.

Request Body:

{
  "content": "What's the weather like in San Francisco?",
  "role": "user"
}

Response:

{
  "id": "msg_125",
  "session_id": "session_123",
  "role": "user",
  "content": "What's the weather like in San Francisco?",
  "created_at": "2023-01-01T00:00:02Z"
}

User Keys

List User Keys

GET /v2/user-keys

Retrieves a list of user keys.

Response:

{
  "user_keys": [
    {
      "id": "uk_123",
      "name": "Web Client",
      "created_at": "2023-01-01T00:00:00Z"
    },
    ...
  ]
}

Create User Key

POST /v2/user-keys

Creates a new user key.

Request Body:

{
  "name": "Mobile Client"
}

Response:

{
  "id": "uk_124",
  "name": "Mobile Client",
  "key": "uk_124_XXXXXXXXXXXXXXXXXXXX",
  "created_at": "2023-01-01T00:00:00Z"
}

Delete User Key

DELETE /v2/user-keys/{user_key_id}

Deletes a user key.

Response:

{
  "success": true
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. See the Error Handling guide for details.

Rate Limiting

The API enforces rate limits to prevent abuse. Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1609459200

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.