Twilio Retrieval API

openapi: 3.2.0
info:
  title: Twilio Memory Retrieval API
  description: APIs for managing memory stores, profiles, and conversational intelligence capabilities.
  version: '1.0'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio Support
    url: https://support.twilio.com
    email: support@twilio.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-twilio:
    apiStandards: v1.0
servers:
- url: https://memory.twilio.com
security:
- accountSid_authToken: []
tags:
- name: Retrieval
  description: The Retrieval APIs resolve profiles and return relevant memory at the moment an agent needs them.
paths:
  /v1/Stores/{storeId}/Profiles/Lookup:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    x-twilio:
      pathType: list
    post:
      operationId: CreateProfilesLookup
      summary: Lookup Profiles
      description: Find profiles that contain a specific identifier value (for example a phone number or email address). Submit an identifier object specifying the `idType` and `value`. The value is normalized using the configured identity resolution settings (such as phone number formatting) prior to matching. Multiple matches are returned if more than one profile is associated with the identifier. Returns canonical profile IDs (the earliest ID if profiles have been merged) along with the normalized value actually searched.
      tags:
      - Retrieval
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Identifier'
            example:
              idType: phone
              value: 1-317-555-6789
      responses:
        '200':
          description: A list of profiles found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  normalizedValue:
                    type: string
                    maxLength: 255
                    description: Identifier value after normalization that was used for the lookup.
                    example: '+13175556789'
                  profiles:
                    type: array
                    maxItems: 100
                    items:
                      $ref: '#/components/schemas/IdentityProfileID'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/Stores/{storeId}/Profiles/{profileId}/Recall:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    - $ref: '#/components/parameters/ProfileId'
    x-twilio:
      pathType: list
    post:
      operationId: CreateFetchProfileMemory
      summary: Retrieve Memories
      description: Tailored memory retrieval for agentic workloads. Supports hybrid semantic search, date ranges, and configurable result limits for different memory types. This endpoint is optimized for conversational AI and memory retrieval use cases. If a query is not specified then one is inferred from the conversation context. If neither a query nor a conversationId is provided, results are returned in most-recent order without relevance scores.
      tags:
      - Retrieval
      parameters:
      - $ref: '#/components/parameters/AcceptEncoding'
      - $ref: '#/components/parameters/ContentEncoding'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryRetrievalRequest'
            examples:
              Basic Query:
                value:
                  query: customer satisfaction feedback
                  conversationId: conv_conversation_00000000000000000000000000
                  communicationsLimit: 10
                  observationsLimit: 20
                  summariesLimit: 5
              Retrieval without Query field:
                value:
                  conversationId: conv_conversation_00000000000000000000000000
                  beginDate: '2025-01-15T00:00:00Z'
                  communicationsLimit: 15
                  observationsLimit: 25
                  summariesLimit: 10
      responses:
        '200':
          description: Memory retrieval results returned successfully.
          headers:
            Content-Encoding:
              $ref: '#/components/headers/ContentEncoding'
            Canonical-Profile-Id:
              $ref: '#/components/headers/Canonical-Profile-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryRetrievalResponse'
              examples:
                Basic Results:
                  value:
                    observations:
                    - id: mem_observation_00000000000000000000000001
                      content: Customer expressed satisfaction with recent product update during support call.
                      source: customer_service
                      occurredAt: '2025-01-15T10:15:30Z'
                      createdAt: '2025-01-15T10:30:45Z'
                      updatedAt: '2025-01-15T10:30:45Z'
                    summaries: []
                    communications: []
                    meta:
                      queryTime: 156
                Retrieval without Query field Results:
                  value:
                    observations: []
                    summaries:
                    - id: mem_summary_00000000000000000000000002
                      conversationId: conv_conversation_00000000000000000000000000
                      content: Recent conversation indicates continued billing visibility concerns; reassurance provided.
                      source: summary_operator
                      occurredAt: '2025-01-15T16:00:00Z'
                      createdAt: '2025-01-15T16:00:10Z'
                      updatedAt: '2025-01-15T16:00:10Z'
                    communications:
                    - id: conv_communication_00000000000000000000000000
                      author:
                        id: conv_participant_00000000000000000000000000
                        name: Customer
                        address: '+12025551234'
                        channel: SMS
                      channelId: SM00000000000000000000000000000000
                      content:
                        text: Hey, I still can't see the new charges on my account.
                      createdAt: '2025-01-15T15:58:10Z'
                      recipients:
                      - id: conv_participant_00000000000000000000000001
                        name: Agent
                        address: '+12025555678'
                        channel: SMS
                    - id: conv_communication_00000000000000000000000001
                      author:
                        id: conv_participant_00000000000000000000000001
                        name: Agent
                        address: '+12025555678'
                        channel: SMS
                      channelId: SM00000000000000000000000000000000
                      content:
                        text: Thanks for checking in. The billing refresh is in progress and should finish shortly.
                      createdAt: '2025-01-15T15:59:05Z'
                      recipients:
                      - id: conv_participant_00000000000000000000000000
                        name: Customer
                        address: '+12025551234'
                        channel: SMS
                    meta:
                      queryTime: 142
        '308':
          $ref: '#/components/responses/PermanentRedirect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    Participant:
      type: object
      required:
      - id
      - name
      - address
      - channel
      properties:
        id:
          type: string
          description: Participant identifier.
          pattern: ^conv_participant_[0-7][0-9a-z]{25}$
          example: conv_participant_00000000000000000000000000
        name:
          type: string
          maxLength: 256
          description: Participant display name
        type:
          $ref: '#/components/schemas/ParticipantType'
          description: Type of Participant in the Conversation
        profileId:
          type: string
          pattern: ^mem_profile_[0-7][0-9a-z]{25}$
          example: mem_profile_00000000000000000000000000
          description: The canonical profile ID.
        address:
          type: string
          description: Address of the Participant (e.g., phone number, email address)
          example: '+12025551234'
          maxLength: 254
        channel:
          type: string
          description: The channel on which the message originated
          enum:
          - VOICE
          - SMS
          - RCS
          - EMAIL
          - WHATSAPP
          - CHAT
          - API
          - SYSTEM
    TwilioError:
      type: object
      additionalProperties: false
      maxProperties: 10
      description: A generic error object communicating client and server side API errors.
      properties:
        code:
          type: integer
          minimum: 100
          maximum: 999999
          description: The Twilio error code.
          format: int32
        message:
          type: string
          maxLength: 1024
          description: A human readable message describing the error.
        more_info:
          type: string
          description: A URL to a [Twilio error directory](https://www.twilio.com/docs/api/errors) page with more information about the error code.
        status:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code for the error.
          format: int32
      example:
        code: 21614
        message: The address specified in the request is not a valid phone number.
        more_info: https://www.twilio.com/docs/api/errors/21614
        status: 400
    RecallSummaryInfo:
      type: object
      description: A summary memory derived from conversations.
      properties:
        source:
          type: string
          description: The source system that generated the summary. Allows letters, numbers, spaces, periods, underscores, hyphens, and forward slashes.
          maxLength: 100
          pattern: ^[a-zA-Z0-9 _./-]+$
          example: conversations
        content:
          type: string
          description: The main content of the summary.
          minLength: 1
          maxLength: 4096
          example: Customer discussed billing concerns and was satisfied with the resolution provided during this conversation.
        occurredAt:
          type: string
          format: date-time
          description: The timestamp when the summary was originally created.
          example: '2025-01-15T10:15:30Z'
        conversationId:
          $ref: '#/components/schemas/ConversationID'
        id:
          $ref: '#/components/schemas/SummaryID'
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the summary was created.
          example: '2025-01-15T10:30:45Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the summary was last updated.
          example: '2025-01-15T10:30:45Z'
        score:
          type: number
          format: double
          description: The relevance score of the summary in relation to the query. Higher values indicate greater relevance. This field is omitted when results are returned in most-recent order. This may occur when no query is provided and one cannot be inferred from the conversation context, or when the system defaults to chronological retrieval to ensure high availability.
          minimum: 0
          maximum: 1
          example: 0.78
      required:
      - content
      - occurredAt
      - id
      - updatedAt
      - createdAt
      - conversationId
    SummaryID:
      type: string
      description: A unique identifier for the summary using Twilio Type ID (TTID) format.
      pattern: ^mem_summary_[0-7][0-9a-z]{25}$
      example: mem_summary_00000000000000000000000000
    ParticipantType:
      type: string
      description: Type of Participant in the Conversation
      enum:
      - HUMAN_AGENT
      - CUSTOMER
      - AI_AGENT
      - AGENT
      - UNKNOWN
    MemoryRetrievalResponse:
      type: object
      description: Response containing retrieved profile memories organized by type.
      properties:
        observations:
          type: array
          description: Array of observation memories.
          maxItems: 100
          items:
            $ref: '#/components/schemas/RecallObservationInfo'
        summaries:
          type: array
          description: Array of summary memories derived from observations at the end of conversations.
          maxItems: 100
          items:
            $ref: '#/components/schemas/RecallSummaryInfo'
        communications:
          type: array
          description: Array of recent communication context.
          minItems: 0
          maxItems: 100
          items:
            $ref: '#/components/schemas/Communication'
        meta:
          type: object
          description: Metadata about the retrieval operation.
          properties:
            queryTime:
              type: integer
              description: Query execution time in milliseconds.
              minimum: 0
              maximum: 600000
              example: 156
          required:
          - queryTime
      required:
      - observations
      - summaries
      - communications
      - meta
    ConversationID:
      type: string
      description: A unique identifier for the conversation using Twilio Type ID (TTID) format.
      pattern: ^conv_conversation_[0-7][0-9a-z]{25}$
      example: conv_conversation_00000000000000000000000000
    IdentityProfileID:
      type: string
      pattern: ^mem_profile_[0-7][0-9a-z]{25}$
      example: mem_profile_00000000000000000000000000
      description: The canonical profile ID.
    Identifier:
      type: object
      additionalProperties: false
      required:
      - idType
      - value
      description: Represents a single identifier value paired with its `idType`. Write operations obey limits, uniqueness, and normalization rules configured via identifier settings.
      properties:
        idType:
          type: string
          description: Identifier type as configured in the service's Identity Resolution Settings.
          minLength: 2
          maxLength: 30
          example: phone
        value:
          type: string
          description: Raw value captured for the identifier. The service may normalize this value according to the `normalization` rule defined in the identifier settings before storage or matching (for example E.164 formatting for phone numbers).
          maxLength: 255
          example: '+13175556789'
    MemoryRetrievalRequest:
      type: object
      description: Request payload for retrieving profile memories with advanced filtering and semantic search.
      properties:
        conversationId:
          $ref: '#/components/schemas/ConversationID'
          description: Required for session memory and query expansion.
        query:
          type: string
          description: Hybrid search query for finding relevant memories. Omit to use query expansion to generate query from previous 10 communications in conversation.
          minLength: 0
          maxLength: 1024
          example: customer satisfaction feedback
        beginDate:
          type: string
          format: date-time
          description: Start date for filtering memories (inclusive).
          example: '2025-01-01T00:00:00Z'
        endDate:
          type: string
          format: date-time
          description: End date for filtering memories (exclusive).
          example: '2025-01-31T23:59:59Z'
        communicationsLimit:
          type: integer
          description: Maximum number of conversational session memories to return. If omitted or set to 0, no session memories will be fetched.
          minimum: 0
          maximum: 100
          default: 0
          example: 10
        observationsLimit:
          type: integer
          description: Maximum number of observation memories to return. If omitted, defaults to 20. If set to 0, no observation memories will be fetched.
          minimum: 0
          maximum: 100
          default: 20
          example: 20
        summariesLimit:
          type: integer
          description: Maximum number of summary memories to return. If omitted, defaults to 5. If set to 0, no summary memories will be fetched.
          minimum: 0
          maximum: 100
          default: 5
          example: 5
        relevanceThreshold:
          type: number
          format: double
          description: Minimum relevance score threshold for observations and summaries to be returned. Only memories with a relevance score greater than or equal to this threshold will be included in the response. This threshold only applies when results are ranked by relevance. When results are returned in most-recent order, this field has no effect.
          minimum: 0
          maximum: 1
          default: 0
          example: 0.5
    Communication:
      type: object
      description: A single communication within a conversation across channels including SMS, Voice, Email, etc. Contains fields that are relevant to an agent to maintain session memory.
      properties:
        id:
          type: string
          description: Unique communication identifier.
          pattern: ^conv_communication_[0-7][0-9a-z]{25}$
          example: conv_communication_00000000000000000000000000
        channelId:
          type: string
          maxLength: 256
          description: Channel-specific ID (optional).
          example: SM00000000000000000000000000000000
        content:
          $ref: '#/components/schemas/CommunicationContent'
        createdAt:
          type: string
          format: date-time
          description: When communication was created.
          example: '2025-01-15T10:15:30Z'
        updatedAt:
          type: string
          format: date-time
          description: When communication was last updated.
          example: '2025-01-15T10:20:30Z'
        author:
          $ref: '#/components/schemas/Participant'
        recipients:
          type: array
          maxItems: 100
          description: Communication recipients
          items:
            type: object
            properties:
              id:
                type: string
                description: Participant identifier.
                pattern: ^conv_participant_[0-7][0-9a-z]{25}$
                example: conv_participant_00000000000000000000000000
              name:
                type: string
                maxLength: 256
                description: Participant display name
              type:
                $ref: '#/components/schemas/ParticipantType'
                description: Type of Participant in the Conversation
              profileId:
                type: string
                pattern: ^mem_profile_[0-7][0-9a-z]{25}$
                example: mem_profile_00000000000000000000000000
                description: The canonical profile ID.
              address:
                type: string
                description: Address of the Participant (e.g., phone number, email address)
                example: '+12025551234'
                maxLength: 254
              channel:
                type: string
                description: The channel on which the message originated
                enum:
                - VOICE
                - SMS
                - RCS
                - EMAIL
                - WHATSAPP
                - CHAT
                - API
                - SYSTEM
              deliveryStatus:
                type: string
                description: Delivery status of the Communication to this recipient
                enum:
                - INITIATED
                - IN_PROGRESS
                - DELIVERED
                - COMPLETED
                - FAILED
            required:
            - id
            - name
            - channel
            - address
      required:
      - id
      - author
      - content
      - recipients
    ObservationID:
      type: string
      description: A unique identifier for the observation using Twilio Type ID (TTID) format.
      pattern: ^mem_observation_[0-7][0-9a-z]{25}$
      example: mem_observation_00000000000000000000000000
    RecallObservationInfo:
      type: object
      description: A transient and mutable observation memory associated with a profile.
      properties:
        content:
          type: string
          description: The main content of the observation.
          minLength: 1
          maxLength: 4096
          example: Customer expressed satisfaction with recent product update during support call.
        occurredAt:
          type: string
          format: date-time
          description: The timestamp when the observation originally occurred.
          example: '2025-01-15T10:15:30Z'
        source:
          type: string
          description: The source system that generated this observation. Allows letters, numbers, spaces, periods, underscores, hyphens, and forward slashes.
          minLength: 1
          maxLength: 100
          pattern: ^[a-zA-Z0-9 _./-]+$
          example: conversational-intelligence
        conversationIds:
          type: array
          description: Array of conversation IDs associated with this observation.
          maxItems: 10
          items:
            $ref: '#/components/schemas/ConversationID'
        id:
          $ref: '#/components/schemas/ObservationID'
        createdAt:
          type: string
          format: date-time
          description: The timestamp when the observation was created.
          example: '2025-01-15T10:30:45Z'
        updatedAt:
          type: string
          format: date-time
          description: The timestamp when the observation was last updated.
          example: '2025-01-15T10:30:45Z'
        score:
          type: number
          format: double
          description: The relevance score of the observation in relation to the query. Higher values indicate greater relevance. This field is omitted when results are returned in most-recent order. This may occur when no query is provided and one cannot be inferred from the conversation context, or when the system defaults to chronological retrieval to ensure high availability.
          minimum: 0
          maximum: 1
          example: 0.82
      required:
      - content
      - id
      - occurredAt
      - updatedAt
      - source
      - createdAt
    CommunicationContent:
      type: object
      description: Content of a communication.
      properties:
        text:
          type: string
          description: Primary text content (optional).
          maxLength: 8388608
          example: Hello, I need help with my account
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20500
            message: Internal Server Error
            more_info: https://www.twilio.com/docs/api/errors/20500
            status: 500
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 403
            message: Permission to access resource denied
            more_info: https://www.twilio.com/docs/api/errors/403
            status: 403
    PermanentRedirect:
      description: This resource has moved.
      content:
        application/json:
          schema:
            type: object
            required:
            - message
            - uri
            properties:
              message:
                type: string
                default: This resource has moved.
                example: This resource has moved.
                maxLength: 255
              uri:
                type: string
                example: https://memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
                maxLength: 2048
            maxProperties: 2
      headers:
        Canonical-Profile-Id:
          $ref: '#/components/headers/Canonical-Profile-Id'
        Location:
          $ref: '#/components/headers/Location'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20404
            message: Not Found
            more_info: https://www.twilio.com/docs/api/errors/20404
            status: 404
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20003
            message: Failed to complete request due to lack of authentication credentials
            more_info: https://www.twilio.com/docs/api/errors/20003
            status: 401
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20503
            message: Service Unavailable
            more_info: https://www.twilio.com/docs/api/errors/20503
            status: 503
    TooManyRequests:
      description: This error indicates that you have sent too many requests to the API. You should retry according to the `Retry-After` response header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20429
            message: Too many requests. Please retry according to the Retry-After response header.
            more_info: https://www.twilio.com/docs/api/errors/20429
            status: 429
      headers:
        Retry-After:
          description: The amount of time in seconds that the customer should wait before issuing a new request towards the API.
          schema:
            type: string
            pattern: ^[0-9]+$
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 400
            message: Failed to complete request due to a bad request
            more_info: https://www.twilio.com/docs/api/errors/400
            status: 400
  headers:
    Location:
      description: The URL of the new location for the resource.
      schema:
        type: string
        format: uri
        example: https:///memory.twilio.com/v1/Stores/mem_store_00000000000000000000000000/Profiles/mem_profile_00000000000000000000000000
        description: The URL of the new location for the resource.
    Canonical-Profile-Id:
      description: The canonical profile ID associated with the requested resource. If provided, this header indicates that the requested profile is merged to the canonical profile ID.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
        description: The canonical profile ID.
    ContentEncoding:
      description: The compression algorithm used for the response body
      schema:
        type: string
        enum:
        - gzip
        - deflate
        - br
        - compress
        example: gzip
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: A unique Memory Store ID using Twilio Type ID (TTID) format
      schema:
        type: string
        pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
        example: mem_store_00000000000000000000000000
    ProfileId:
      name: profileId
      in: path
      required: true
      description: The unique identifier for the profile using Twilio Type ID (TTID) format.
      schema:
        type: string
        pattern: ^mem_profile_[0-7][0-9a-z]{25}$
        example: mem_profile_00000000000000000000000000
    ContentEncoding:
      name: Content-Encoding
      in: header
      required: false
      description: Compression algorithm used for the request body (e.g., gzip, deflate, br)
      schema:
        type: string
        enum:
        - gzip
        - deflate
        - br
        - compress
        example: gzip
    AcceptEncoding:
      name: Accept-Encoding
      in: header
      required: false
      description: Compression algorithms supported by the client (e.g., gzip, deflate, br)
      schema:
        type: string
        maxLength: 200
        pattern: ^[a-zA-Z0-9, .-]*$
        example: gzip, deflate, br
  securitySchemes:
    basic_apikey_or_accountsid:
      scheme: basic
      type: http
      description: This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing.
    accountSid_authToken:
      scheme: basic
      type: http