> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflecto.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up a saved contact to text, by name

> The `find_contact` MCP tool's backing endpoint. Asks the user's phone to search its contacts by name and waits up to **15 seconds** for the answer. Returns up to 5 candidates, each a display name, a number-type label and an opaque single-use handle (10-minute lifetime) for `POST /v1/sms-agent/sends`.

**No phone number is ever returned**, whole or in part, and a query that is mostly digits is refused (`400 invalid_query`) so this cannot become a reverse lookup.

**Not end-to-end encrypted.** This is Reflecto's server-as-sender path: the request passes through Reflecto's server in memory, is encrypted to the phone with the server's key, and is never stored.

Requires an OAuth token from a connected assistant holding `sms:send`, and a paired phone running a Reflecto build that supports assistant texting (`426` / `428` otherwise). The user must also have switched on “Let assistants send texts” on the phone, or the answer is `disabled`.



## OpenAPI

````yaml /openapi.yaml post /v1/sms-agent/contact-queries
openapi: 3.1.0
info:
  title: Reflecto API
  version: 1.1.0
  description: >-
    The Reflecto public HTTP API lets you push notifications to your own paired

    devices — your Android phone and any browser extensions you've paired with
    it.

    Designed for the same job as Pushover or the old Pushbullet API: a single

    HTTPS call from a script, cron job, or webhook puts a notification on every

    screen you own.


    Authentication uses opaque prefixed bearer tokens (`rfk_live_…`) created and

    managed on your paired Android device — there are no email accounts, no

    passwords, no server-side user records beyond device pairing state. See the

    Authentication guide for the token lifecycle.


    The public-API surface is small on purpose: `POST /v1/send`, its

    capability-URL alias `POST /v1/send/{token}`, and a Pushover-compatible shim

    at `POST /v1/messages.json`. Mirroring traffic from your phone to your

    extension never reaches this surface — it stays end-to-end encrypted via the

    private `/v1/sync` SSE stream.


    See the Guides tab for the quickstart, authentication model, rate-limit

    contract, and encryption posture.
  contact:
    name: Reflecto
    url: https://github.com/reflectoapp/reflecto
  license:
    name: MIT
    url: https://github.com/reflectoapp/reflecto/blob/main/LICENSE
servers:
  - url: https://api.reflecto.dev
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Send
    description: Push notifications to one or all of your paired devices.
  - name: Pushover compatibility
    description: >-
      Drop-in replacement for `POST https://api.pushover.net/1/messages.json`.
      Field names, request shape, and response shape mirror Pushover's so
      existing senders can migrate by changing a single URL. See [Pushover
      compatibility guide](/guides/pushover-compatibility) for the full mapping.
paths:
  /v1/sms-agent/contact-queries:
    post:
      tags:
        - SMS (assistant)
      summary: Look up a saved contact to text, by name
      description: >-
        The `find_contact` MCP tool's backing endpoint. Asks the user's phone to
        search its contacts by name and waits up to **15 seconds** for the
        answer. Returns up to 5 candidates, each a display name, a number-type
        label and an opaque single-use handle (10-minute lifetime) for `POST
        /v1/sms-agent/sends`.


        **No phone number is ever returned**, whole or in part, and a query that
        is mostly digits is refused (`400 invalid_query`) so this cannot become
        a reverse lookup.


        **Not end-to-end encrypted.** This is Reflecto's server-as-sender path:
        the request passes through Reflecto's server in memory, is encrypted to
        the phone with the server's key, and is never stored.


        Requires an OAuth token from a connected assistant holding `sms:send`,
        and a paired phone running a Reflecto build that supports assistant
        texting (`426` / `428` otherwise). The user must also have switched on
        “Let assistants send texts” on the phone, or the answer is `disabled`.
      operationId: findSmsContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsContactQueryRequest'
            examples:
              byName:
                value:
                  query: Richa mobile
      responses:
        '200':
          description: >-
            The phone's answer, or `phone_unreachable` if it did not answer
            within 15 s. Every outcome is a 200 — only `ok` carries candidates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsContactQueryResponse'
              examples:
                ok:
                  value:
                    status: ok
                    candidates:
                      - handle: ch_q3V9xK2mP0aL7bN4cR1sTw
                        name: Richa Sharma
                        label: Mobile
                      - handle: ch_Zx8wV7uT6sR5qP4oN3mL2k
                        name: Richa Sharma
                        label: Work
                noMatch:
                  value:
                    status: no_match
                unreachable:
                  value:
                    status: phone_unreachable
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '426':
          $ref: '#/components/responses/UpgradeRequired'
        '428':
          $ref: '#/components/responses/PreconditionRequired'
        '429':
          $ref: '#/components/responses/RateLimitedInteractions'
      security:
        - ConnectorOAuth: []
components:
  schemas:
    SmsContactQueryRequest:
      type: object
      properties:
        query:
          type: string
          description: >-
            The contact's name as the user said it, including a number type
            (Mobile/Work/Home) if they said one. Never a phone number: a query
            that is mostly digits is refused.
          example: Richa mobile
      required:
        - query
      additionalProperties: false
    SmsContactQueryResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - no_match
            - too_many
            - disabled
            - too_many_lookups
            - no_contacts_permission
            - no_sms_permission
            - invalid_query
            - contacts_unavailable
            - phone_unreachable
          description: >-
            `ok` carries 1–5 candidates. `no_match` / `too_many` (more than 5 —
            ask for a more specific name) carry none. `disabled` = the user has
            not switched on “Let assistants send texts” on the phone.
            `phone_unreachable` = the phone did not answer within 15 s. The
            remaining values are phone-side refusals: `too_many_lookups`
            (30/hour), `no_contacts_permission`, `no_sms_permission`,
            `invalid_query`, `contacts_unavailable`.
          example: ok
        candidates:
          type: array
          items:
            type: object
            properties:
              handle:
                type: string
                pattern: ^ch_[A-Za-z0-9_-]{22}$
                description: >-
                  Opaque, single-use, 10-minute handle minted by the phone. The
                  ONLY way to name a recipient for `POST /v1/sms-agent/sends`.
                example: ch_q3V9xK2mP0aL7bN4cR1sTw
              name:
                type: string
                minLength: 1
                maxLength: 200
                description: The contact's display name.
                example: Richa Sharma
              label:
                type: string
                minLength: 1
                maxLength: 100
                description: >-
                  The number type (localized, or the contact's custom label).
                  Never a number.
                example: Mobile
              recency:
                type: string
                enum:
                  - texted today
                  - texted yesterday
                  - texted this week
                  - texted earlier
                description: >-
                  Coarse last-texted bucket. Present only to tell apart two
                  candidates with the same name and label. Never a timestamp.
                example: texted yesterday
            required:
              - handle
              - name
              - label
            additionalProperties: false
          description: Present only when `status` is `ok`. Never contains a phone number.
      required:
        - status
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: message_too_long
            message:
              type: string
              example: message must be ≤ 1500 bytes
            details:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
      required:
        - error
    SimpleErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        message:
          type: string
      required:
        - error
      description: >-
        Flat error shape used for auth failures — `invalid_token` carries only
        the stable code; `missing_token` adds a `message` hint pointing at the
        `Authorization: Bearer …` header. The `message` field is therefore
        optional.
  responses:
    BadRequest:
      description: Malformed payload or invalid field value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidPriority:
              value:
                error:
                  code: invalid_priority
                  message: priority must be one of min, low, default, high, urgent
            messageTooLong:
              value:
                error:
                  code: message_too_long
                  message: message must be ≤ 1500 bytes
                  details:
                    bytes: 1620
                    max: 1500
    Unauthorized:
      description: Missing, invalid, or revoked bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleErrorResponse'
          examples:
            missingToken:
              value:
                error: missing_token
                message: 'Authorization: Bearer rfk_live_… required'
            invalidToken:
              value:
                error: invalid_token
    Forbidden:
      description: Token exists but lacks scope for the requested action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            priorityCapped:
              value:
                error:
                  code: priority_capped
                  message: Token's priority_cap is 'default'; requested 'high'
    Conflict:
      description: The request conflicts with the current state of a resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            noPhoneDevice:
              summary: Owner has no paired phone to ask
              value:
                error:
                  code: no_phone_device
                  message: no_phone_device
    UpgradeRequired:
      description: >-
        The target phone's Reflecto app is too old to receive this — update
        Reflecto on the phone from the Google Play Store before this can be
        delivered. Nothing was sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            phoneAppOutdated:
              value:
                error:
                  code: phone_app_outdated
                  message: >-
                    the paired phone's Reflecto app is too old to receive this —
                    update Reflecto on the phone from the Google Play Store
                    before this can be delivered; nothing was sent.
    PreconditionRequired:
      description: >-
        The paired phone hasn't reported its Reflecto app version, so support
        can't be confirmed — the user should update Reflecto and open it once.
        Nothing was sent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            phoneAppUnknown:
              value:
                error:
                  code: phone_app_unknown
                  message: >-
                    Reflecto can't confirm the user's phone supports texting for
                    an assistant. Ask the user to update Reflecto on their phone
                    and open it once, then try again; nothing was sent.
    RateLimitedInteractions:
      description: >-
        Rate limit or resource cap exceeded. For interaction creation this
        includes the 10-pending-per-owner cap; for ring and reminders, IP/token
        rate limits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimitExceeded:
              value:
                error:
                  code: rate_limit_exceeded
                  message: Rate limit hit
            tooManyPending:
              summary: Owner already has 10 pending interactions
              value:
                error:
                  code: too_many_pending
                  message: too_many_pending
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rfk_live_…
      description: >-
        Opaque bearer token created on your paired Android phone. The format is
        `rfk_live_` followed by 32 URL-safe alphanumeric characters (≥160 bits
        of entropy). Test tokens use the `rfk_test_` prefix.
    ConnectorOAuth:
      type: http
      scheme: bearer
      description: >-
        OAuth 2.1 access token issued by Reflecto's authorization server to a
        connected AI assistant (the remote MCP connector flow). Must carry the
        `sms:send` scope, which is never granted to `rfk_live_` API tokens.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.