> ## 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. # Ring your paired phone (find_my_phone) > Sends a high-priority "ring" command to your paired phone over FCM so you can locate it — the `find_my_phone` MCP tool's backing endpoint. **Fire-and-forget by design (spec D10).** There is no queue entry and no retry: a phone that was off or offline when this fired must not suddenly ring an hour later, so an undeliverable command is dropped, not queued. The endpoint always returns `202` once the request is accepted — the server has no delivery receipt for FCM, so it cannot confirm the phone actually rang. Reachability is instead surfaced honestly via `warnings`: an empty/absent array means the phone had a push registration and the FCM send was accepted; a non-empty array (e.g. `"phone has no push registration — may be unreachable"`) means the ring may never arrive. This is not a delivery guarantee either way — only the best information the server has. **Owner-scoped and phone-only.** `{deviceId}` must be the caller's own device id and must be a phone-kind device — a non-phone id returns `409 no_phone_device`. A foreign or unknown id is indistinguishable from `404 not_found`: cross-tenant device existence is never confirmed. Requires the `phone:control` scope (`403 insufficient_scope` otherwise) and is charged against the same per-token send-class limits as `POST /v1/interactions`. **Phone-capability gate.** If the paired phone's reported app build predates ring support, the request is refused outright (`426 phone_app_outdated`) rather than accepted and silently dropped as an unrecognized FCM message. A phone that has never reported its version rings anyway, with a `warnings` entry naming the uncertainty. ## OpenAPI ````yaml /openapi.yaml post /v1/devices/{deviceId}/ring 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/devices/{deviceId}/ring: post: tags: - Devices summary: Ring your paired phone (find_my_phone) description: >- Sends a high-priority "ring" command to your paired phone over FCM so you can locate it — the `find_my_phone` MCP tool's backing endpoint. **Fire-and-forget by design (spec D10).** There is no queue entry and no retry: a phone that was off or offline when this fired must not suddenly ring an hour later, so an undeliverable command is dropped, not queued. The endpoint always returns `202` once the request is accepted — the server has no delivery receipt for FCM, so it cannot confirm the phone actually rang. Reachability is instead surfaced honestly via `warnings`: an empty/absent array means the phone had a push registration and the FCM send was accepted; a non-empty array (e.g. `"phone has no push registration — may be unreachable"`) means the ring may never arrive. This is not a delivery guarantee either way — only the best information the server has. **Owner-scoped and phone-only.** `{deviceId}` must be the caller's own device id and must be a phone-kind device — a non-phone id returns `409 no_phone_device`. A foreign or unknown id is indistinguishable from `404 not_found`: cross-tenant device existence is never confirmed. Requires the `phone:control` scope (`403 insufficient_scope` otherwise) and is charged against the same per-token send-class limits as `POST /v1/interactions`. **Phone-capability gate.** If the paired phone's reported app build predates ring support, the request is refused outright (`426 phone_app_outdated`) rather than accepted and silently dropped as an unrecognized FCM message. A phone that has never reported its version rings anyway, with a `warnings` entry naming the uncertainty. operationId: ringDevice parameters: - schema: type: string description: >- The phone device id to ring — must be the caller's own paired phone. example: dev_9af3 required: true description: The phone device id to ring — must be the caller's own paired phone. name: deviceId in: path responses: '202': description: >- Ring command accepted. Whether it will actually reach the phone is reported in `warnings`, not the status code. content: application/json: schema: $ref: '#/components/schemas/RingResponse' examples: requested: summary: Phone has an active push registration value: status: requested unreachable: summary: Phone has no push registration — may not receive the ring value: status: requested warnings: - phone has no push registration — may be unreachable '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '426': $ref: '#/components/responses/UpgradeRequired' '429': $ref: '#/components/responses/RateLimitedInteractions' security: - BearerAuth: [] components: schemas: RingResponse: type: object properties: status: type: string enum: - requested description: >- Always "requested" — the ring is fire-and-forget (D10): the server never learns whether the phone actually rang, only whether the FCM send was attempted. example: requested warnings: type: array items: type: string description: >- Caveats about this ring, present for either of two independent reasons: the target phone had no push registration (or the FCM send failed) — the ring may never arrive — OR the phone's reported app version is unknown (see the phone-capability gate above), in which case the ring is still sent but the uncertainty is named here. The second reason can appear even after a fully successful send, so a non-empty array is not itself a failure signal; omitted entirely only when neither caveat applies, and even then its absence is not a delivery guarantee, only a lack of a known reason it would fail. example: - phone has no push registration — may be unreachable required: - status 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. 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 responses: 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' NotFound: description: >- The requested resource does not exist or is not visible to this principal. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: >- Unknown interaction id, one past its 24h retention window, or owned by a different principal — cross-principal reads are deliberately indistinguishable from unknown ids (never confirm existence to the wrong owner) value: error: code: not_found message: not_found 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. 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. ````