Samu

Samu Threads API

Conversaciones (threads/messages/interactions) de WhatsApp y otros providers

GitHub OpenAPI

Operations 4

GET /api/chat/threads List threads (inbox)
GET /api/chat/threads/{threadId} Get a single thread
GET /api/chat/threads/{threadId}/messages List messages in a thread (paginated)
GET /api/chat/threads/{threadId}/interactions Lista las interacciones diarias de un thread (con summary y extractor)

Documentation

📖
Documentation
https://api.samu.ai/docs
📖
APIReference
https://api.samu.ai/docs
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/authentication/samu-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/rate-limits/samu-rate-limits.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/openapi/samu-threads-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/conventions/samu-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/data-model/samu-data-model.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/samu/refs/heads/main/errors/samu-problem-types.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/samu-threads-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

samu-threads-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Samu Threads API
  version: 1.0.1
  description: Documentación de la API de Samu.ai
servers:
- url: https://api.samu.ai
tags:
- name: Threads
  description: Conversaciones (threads/messages/interactions) de WhatsApp y otros providers
paths:
  /api/chat/threads:
    get:
      summary: List threads (inbox)
      tags:
      - Threads
      security:
      - ApiKeyAuth: []
      parameters:
      - in: query
        name: provider
        schema:
          $ref: '#/components/schemas/ChatProvider'
      - in: query
        name: threadType
        schema:
          $ref: '#/components/schemas/ConversationThreadType'
      - in: query
        name: dateFrom
        schema:
          type: string
          format: date-time
        description: Filtra threads cuya última actividad (lastMessageAt) es >= al inicio de este día en UTC (inclusivo por día).
      - in: query
        name: dateTo
        schema:
          type: string
          format: date-time
        description: Filtra threads cuya última actividad (lastMessageAt) es <= al fin de este día en UTC (inclusivo por día).
      - in: query
        name: cursor
        schema:
          type: string
          format: date-time
      - in: query
        name: limit
        schema:
          type: integer
      responses:
        '200':
          description: Thread page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationThreadListItem'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    format: date-time
  /api/chat/threads/{threadId}:
    get:
      summary: Get a single thread
      tags:
      - Threads
      security:
      - ApiKeyAuth: []
      parameters:
      - in: path
        name: threadId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Thread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationThreadListItem'
  /api/chat/threads/{threadId}/messages:
    get:
      summary: List messages in a thread (paginated)
      tags:
      - Threads
      security:
      - ApiKeyAuth: []
      parameters:
      - in: path
        name: threadId
        required: true
        schema:
          type: string
      - in: query
        name: before
        schema:
          type: string
          format: date-time
      - in: query
        name: from
        schema:
          type: string
          format: date-time
        description: Solo mensajes con sentAt >= al inicio de este día en UTC (inclusivo por día). Acota el historial de threads largos.
      - in: query
        name: to
        schema:
          type: string
          format: date-time
        description: Solo mensajes con sentAt <= al fin de este día en UTC (inclusivo por día).
      - in: query
        name: limit
        schema:
          type: integer
      responses:
        '200':
          description: Message page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationMessageItem'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                    format: date-time
  /api/chat/threads/{threadId}/interactions:
    get:
      summary: Lista las interacciones diarias de un thread (con summary y extractor)
      tags:
      - Threads
      security:
      - ApiKeyAuth: []
      parameters:
      - in: path
        name: threadId
        required: true
        schema:
          type: string
      - in: query
        name: from
        schema:
          type: string
          format: date-time
        description: Solo interacciones con date >= al inicio de este día en UTC (inclusivo por día).
      - in: query
        name: to
        schema:
          type: string
          format: date-time
        description: Solo interacciones con date <= al fin de este día en UTC (inclusivo por día).
      - in: query
        name: page
        schema:
          type: integer
          default: 1
      - in: query
        name: perPage
        schema:
          type: integer
          default: 50
        description: Máximo 200
      responses:
        '200':
          description: Página de interacciones diarias
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationInteractionItem'
                  total:
                    type: integer
                  page:
                    type: integer
                  perPage:
                    type: integer
components:
  schemas:
    ConversationThreadType:
      type: string
      enum:
      - dm
      - group
    ConversationThreadListItem:
      type: object
      description: Item del listado de conversaciones (threads)
      properties:
        id:
          type: string
        owner:
          type:
          - object
          - 'null'
          description: Datos del host (owner) del thread
          properties:
            id:
              type: string
            email:
              type: string
            name:
              type: string
            lastName:
              type: string
        title:
          type:
          - string
          - 'null'
          description: Nombre de la conversación. En grupos (threadType=group) es el nombre del grupo; en DM es el nombre del contacto.
        provider:
          $ref: '#/components/schemas/ChatProvider'
        threadType:
          $ref: '#/components/schemas/ConversationThreadType'
        lastMessageAt:
          type: string
          format: date-time
        contacts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              lastName:
                type: string
              phone:
                type: string
              mobilePhone:
                type: string
              email:
                type: string
    ConversationMessageItem:
      type: object
      description: Mensaje en el shape público (import)
      properties:
        id:
          type: string
        direction:
          type: string
          enum:
          - inbound
          - outbound
        sender:
          type: object
          properties:
            kind:
              type: string
              enum:
              - contact
              - user
              - provider_identity
            contactId:
              type: string
              description: Cruzar con thread.contacts para el nombre
            userId:
              type: string
        sentAt:
          type: string
          format: date-time
        content:
          type: object
          properties:
            type:
              type: string
              enum:
              - text
              - audio
              - image
              - video
              - document
            text:
              type: string
        attachments:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              filename:
                type: string
              mime:
                type: string
              size:
                type: number
    ChatProvider:
      type: string
      enum:
      - WHATSAPP
      - HUBSPOT
      - EMAIL
    ConversationInteractionItem:
      type: object
      description: Interacción diaria de un thread (snapshot del día)
      properties:
        id:
          type: string
        date:
          type: string
          format: date-time
          description: Día de la interacción
        summary:
          type: string
          description: Resumen del día (metadata.extractor.samu_longSummary ?? samu_summary)
        extractor:
          type: object
          description: Props custom que Samu extrajo ese día (campos no samu_*)
        actionItems:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              description:
                type: string
              status:
                type: string
              dueAt:
                type: string
                format: date-time
              resolvedAt:
                type: string
                format: date-time
        status:
          type: string
          description: Estado del procesamiento diario (output.sync_daily_status)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apiKey
      description: API key de la cuenta