Skip to content

AI Conversations

Reference for the ai_conversations endpoints of the Surfmeter API.

Surfmeter API – AI Conversations v1

The Surfmeter API lets you manage clients, users, capabilities, measurements, and organization-wide settings programmatically.

Servers

Description URL
https://surfmeter-server.{host}/client_admin_api/v1 https://surfmeter-server.{host}/client_admin_api/v1

AI Conversations

GET /ai_conversations

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Response 200 OK 

{
    "conversations": [
        {
            "id": 0,
            "title": "string",
            "display_title": "string",
            "preview": "string",
            "message_count": 0,
            "created_at": "2026-01-15T10:30:00Z",
            "updated_at": "2026-01-15T10:30:00Z"
        }
    ]
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "conversations"
    ],
    "additionalProperties": false,
    "properties": {
        "conversations": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "id",
                    "title",
                    "display_title",
                    "preview",
                    "message_count",
                    "created_at",
                    "updated_at"
                ],
                "additionalProperties": false,
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string",
                        "nullable": true
                    },
                    "display_title": {
                        "type": "string"
                    },
                    "preview": {
                        "type": "string"
                    },
                    "message_count": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-01-15T10:30:00Z"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "example": "2026-01-15T10:30:00Z"
                    }
                }
            }
        }
    }
}

POST /ai_conversations

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Request body

{
    "title": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "required": [
        "title"
    ],
    "additionalProperties": false,
    "properties": {
        "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
        }
    }
}

Response 201 Created 

{
    "conversation": {
        "id": 0,
        "title": "string",
        "display_title": "string",
        "preview": "string",
        "message_count": 0,
        "messages": [
            {}
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "conversation"
    ],
    "additionalProperties": false,
    "properties": {
        "conversation": {
            "type": "object",
            "required": [
                "id",
                "title",
                "display_title",
                "preview",
                "message_count",
                "messages",
                "created_at",
                "updated_at"
            ],
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "integer"
                },
                "title": {
                    "type": "string",
                    "nullable": true
                },
                "display_title": {
                    "type": "string"
                },
                "preview": {
                    "type": "string"
                },
                "message_count": {
                    "type": "integer",
                    "minimum": 0
                },
                "messages": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                }
            }
        }
    }
}

GET /ai_conversations/{id}

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id path string No

Response 200 OK 

{
    "conversation": {
        "id": 0,
        "title": "string",
        "display_title": "string",
        "preview": "string",
        "message_count": 0,
        "messages": [
            {
                "id": "string",
                "role": "user",
                "parts": [
                    {}
                ]
            }
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "conversation"
    ],
    "additionalProperties": false,
    "properties": {
        "conversation": {
            "type": "object",
            "required": [
                "id",
                "title",
                "display_title",
                "preview",
                "message_count",
                "messages",
                "created_at",
                "updated_at"
            ],
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "integer"
                },
                "title": {
                    "type": "string",
                    "nullable": true
                },
                "display_title": {
                    "type": "string"
                },
                "preview": {
                    "type": "string"
                },
                "message_count": {
                    "type": "integer",
                    "minimum": 0
                },
                "messages": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": [
                            "id",
                            "role",
                            "parts"
                        ],
                        "additionalProperties": true,
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "role": {
                                "type": "string",
                                "enum": [
                                    "user",
                                    "assistant",
                                    "system"
                                ]
                            },
                            "parts": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            }
                        }
                    }
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                }
            }
        }
    }
}

PATCH /ai_conversations/{id}

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id path string No

Request body

{
    "title": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "required": [
        "title"
    ],
    "additionalProperties": false,
    "properties": {
        "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
        }
    }
}

Response 200 OK 

{
    "conversation": {
        "id": 0,
        "title": "string",
        "display_title": "string",
        "preview": "string",
        "message_count": 0,
        "messages": [
            {}
        ],
        "created_at": "2026-01-15T10:30:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
{
    "type": "object",
    "required": [
        "conversation"
    ],
    "additionalProperties": false,
    "properties": {
        "conversation": {
            "type": "object",
            "required": [
                "id",
                "title",
                "display_title",
                "preview",
                "message_count",
                "messages",
                "created_at",
                "updated_at"
            ],
            "additionalProperties": false,
            "properties": {
                "id": {
                    "type": "integer"
                },
                "title": {
                    "type": "string",
                    "nullable": true
                },
                "display_title": {
                    "type": "string"
                },
                "preview": {
                    "type": "string"
                },
                "message_count": {
                    "type": "integer",
                    "minimum": 0
                },
                "messages": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "created_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                },
                "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "example": "2026-01-15T10:30:00Z"
                }
            }
        }
    }
}

DELETE /ai_conversations/{id}

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id path string No

Response 200 OK

PUT /ai_conversations/{id}/complete

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id path string No

Request body

{
    "title": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "required": [
        "title"
    ],
    "additionalProperties": false,
    "properties": {
        "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
        }
    }
}

Response 200 OK

PATCH /ai_conversations/{id}/generated_title

Input parameters

Parameter In Type Default Nullable Description
ApiKeyAuth header string N/A No API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id path string No

Request body

{
    "title": "string"
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
{
    "type": "object",
    "required": [
        "title"
    ],
    "additionalProperties": false,
    "properties": {
        "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
        }
    }
}

Response 200 OK

Schemas

AiConversationCreateResponse

Name Type
conversation Properties: id, title, display_title, preview, message_count, messages, created_at, updated_at

AiConversationIndexResponse

Name Type
conversations Array<Properties: id, title, display_title, preview, message_count, created_at, updated_at>

AiConversationShowResponse

Name Type
conversation Properties: id, title, display_title, preview, message_count, messages, created_at, updated_at

AiConversationUpdateData

Name Type
title string

AiConversationUpdateResponse

Name Type
conversation Properties: id, title, display_title, preview, message_count, messages, created_at, updated_at

Security schemes

Name Type Scheme Description
ApiKeyAuth apiKey API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.