openapi: 3.2.0
info:
  title: Twilio Memory Store 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: Store
  description: The Memory Store is the parent container for all Conversation Memory data. Profiles, identifiers, traits, observations, and summaries all live inside a specific store, and that store defines the boundary for how data is organized and resolved. A store must be created before you create a conversation configuration, because the conversation configuration needs to know where profiles and memory should be written.
paths:
  /v1/ControlPlane/Stores:
    servers:
    - url: https://memory.twilio.com
    x-twilio:
      pathType: list
    get:
      operationId: ListStores
      summary: List Memory Stores
      description: Get a list of memory stores for the Twilio account.
      tags:
      - Store
      parameters:
      - $ref: '#/components/parameters/ControlPlanePageSize'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: Memory stores retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: CreateStore
      summary: Create a Memory Store
      description: 'Create a new Memory Store for the Twilio account. Accounts can have multiple memory stores, up to a maximum limit of 15.

        Each memory store will automatically provision other dependent resources as needed, including Conversational Intelligence

        capabilities.'
      tags:
      - Store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest'
      responses:
        '202':
          description: Store creation accepted for async processing. Inspect the status URL for progress.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Memory Store creation accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/ControlPlane/Stores/{storeId}:
    servers:
    - url: https://memory.twilio.com
    parameters:
    - $ref: '#/components/parameters/StoreId'
    x-twilio:
      defaultOutputProperties:
      - id
      - uniqueName
      - friendlyName
      pathType: instance
    get:
      operationId: FetchStore
      summary: Retrieve a Memory Store
      description: Retrieve the details of a specific Memory Store by its unique ID.
      tags:
      - Store
      responses:
        '200':
          description: Memory Store details retrieved successfully
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      operationId: PatchStore
      parameters:
      - $ref: '#/components/parameters/IfMatchHeader'
      summary: Update a Memory Store
      description: Partially update a Memory Store. Only the fields provided in the request body will be updated.
      tags:
      - Store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                displayName:
                  type: string
                  description: Provides a unique and addressable name to be assigned to this Store. This name is assigned by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within the account.
                  pattern: ^[a-zA-Z0-9-]+$
                  maxLength: 64
                  example: sandbox-updated
                description:
                  type: string
                  description: A human readable description of this resource, up to 128 characters.
                  minLength: 1
                  maxLength: 128
                  example: Updated service for development and testing
      responses:
        '202':
          description: Memory Store update request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Memory Store update request accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      operationId: DeleteStore
      summary: Delete a Memory Store
      description: Deletes the Memory Store and all associated resources including identity resolution settings, trait groups, profiles, traits, observations, and summaries.
      tags:
      - Store
      responses:
        '202':
          description: Memory Store deletion request accepted.
          headers:
            Operation-Id:
              $ref: '#/components/headers/OperationId'
            Location:
              $ref: '#/components/headers/OperationLocation'
            Retry-After:
              $ref: '#/components/headers/OperationRetryAfter'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  message:
                    type: string
                    maxLength: 512
                    example: Memory Store deletion request accepted for processing.
                  statusUrl:
                    type: string
                    description: URI to check operation status.
                    maxLength: 512
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  headers:
    OperationId:
      description: The operation identifier.
      schema:
        type: string
        maxLength: 512
    OperationLocation:
      description: URI to check operation status.
      schema:
        type: string
        maxLength: 512
    OperationRetryAfter:
      description: Suggested number of seconds to wait before checking status again.
      schema:
        type: integer
    ETag:
      description: 'Entity tag that acts as a unique identifier for a specific version of the resource.

        Send updates with If-Match conditional headers for optimistic concurrency control.'
      schema:
        type: string
        maxLength: 512
      example: eyJpZCI6ImFuX2lkIiwidiI6MX0
  schemas:
    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
    Meta:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          maxLength: 64
          description: 'The key of the list property contains the actual data items.

            This enables programmatic iteration over paginated results.

            '
        pageSize:
          type: integer
          description: The number of items returned in this page of results.
        nextToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
        previousToken:
          type: string
          maxLength: 4096
          example: eyJlYXN0ZXIiOiJlZ2cifQ
    ServiceRequest:
      type: object
      properties:
        displayName:
          type: string
          description: Provides a unique and addressable name to be assigned to this Store. This name is assigned by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within the account.
          pattern: ^[a-zA-Z0-9-]+$
          maxLength: 64
          example: sandbox
        description:
          type: string
          description: A human readable description of this resource, up to 128 characters.
          minLength: 1
          maxLength: 128
          example: A testing ground for development, training, and experimentation without affecting live user data
      required:
      - displayName
    ServiceList:
      type: object
      additionalProperties: false
      properties:
        stores:
          type: array
          maxItems: 100
          items:
            type: string
            pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
          description: List of Memory Store IDs associated with the Twilio account.
          example:
          - mem_store_0123456789abcdefghijklmnop
          - mem_store_1123456789abcdefghijklmnop
          - mem_store_2123456789abcdefghijklmnop
          - mem_store_3123456789abcdefghijklmnop
        meta:
          $ref: '#/components/schemas/Meta'
    Store:
      type: object
      properties:
        displayName:
          type: string
          description: Provides a unique and addressable name to be assigned to this Store. This name is assigned by the developer and can be used in addition to the ID. It is intended to be human-readable and unique within the account.
          pattern: ^[a-zA-Z0-9-]+$
          maxLength: 64
          example: sandbox
        description:
          type: string
          description: A human readable description of this resource, up to 128 characters.
          minLength: 1
          maxLength: 128
          example: A testing ground for development, training, and experimentation without affecting live user data
        id:
          type: string
          description: The unique identifier for the Memory Store
          pattern: ^mem_(store|service)_[0-7][0-9a-z]{25}$
          example: mem_store_00000000000000000000000000
        status:
          type: string
          description: The current status of the Memory Store.  A store begins in the QUEUED state as it is scheduled for processing.  It then moves to PROVISIONING at the beginning of processing. It transitions to ACTIVE once all dependent resources are provisioned, including Conversational Intelligence capabilities.  If there is an issue provisioning resources, the store will move to the FAILED state.
          enum:
          - QUEUED
          - PROVISIONING
          - ACTIVE
          - FAILED
          example: ACTIVE
        intelligenceServiceId:
          type:
          - string
          - 'null'
          maxLength: 64
          description: The ID of the associated intelligence service that was provisioned for memory extraction.
          example: intelligence_service_00000000000000000000000000
        version:
          type: integer
          minimum: 1
          description: The current version number of the Memory Store. Incremented on each successful update.
          example: 3
      required:
      - displayName
      - status
      - id
      - intelligenceServiceId
      - version
  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
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TwilioError'
          example:
            code: 20412
            message: Precondition Failed
            more_info: https://www.twilio.com/docs/api/errors/20412
            status: 412
    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
    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
  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
    IfMatchHeader:
      in: header
      name: If-Match
      description: 'Allows for optimistic concurrency control by making the request conditional.

        Server will only act if the resource''s current Entity Tag (ETag) matches

        the one provided, preventing accidental overwrites.'
      schema:
        type: string
        maxLength: 100
        example: '"eyJpZCI6ImFuX2lkIiwidiI6MX0"'
    PageToken:
      name: pageToken
      in: query
      required: false
      description: The token for the page of results to retrieve.
      schema:
        type: string
        maxLength: 4096
    OrderBy:
      name: orderBy
      in: query
      required: false
      description: Either 'ASC' or 'DESC' to sort results ascending or descending respectively.
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    ControlPlanePageSize:
      name: pageSize
      in: query
      required: false
      description: The maximum number of items to return per page, maximum of 100.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
  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