Skip to content

API reference

Use MCP to discover approved phone data, then read it through MCP or REST. Public catalog and documentation requests need no account. For setup, start with Getting started.

Authenticate

Connect a Streamable HTTP MCP client to:

https://myself.md/mcp

Use protected-resource metadata and authorization-server metadata to find the issuer and registration, authorization and token endpoints.

Sign in with the authorization-code flow and PKCE. Request the myselfmd scope for the MCP resource. The owner completes sign-in and consent, pairs a phone, and approves the profiles and data types the agent can read. An agent cannot grant itself access, and a shared API key cannot replace consent.

Private requests need an agent OAuth bearer token. Missing or expired tokens return HTTP 401 with a WWW-Authenticate discovery header. Keep tokens out of URLs and public source code.

Discover available data

After MCP initialization, call tools/list for the current schemas, inputs and limits.

  1. Discover the owner’s paired phones.
  2. Call get_phone_data_catalog for available data types and approved profiles.
  3. Choose a supported type covered by the profile and its data grants.
  4. Call query_phone_data, then poll get_phone_request for the result.

Use the returned identifiers rather than guessing them. create_phone_export_profile submits a profile for owner review; it does not grant access.

A phone read may need the app open and OS permissions enabled. Sign-in, permission prompts, purchases and system sharing require the owner on the device. Empty HealthKit results can mean missing records or limited permission; they do not prove authorization.

Try the fictional-data demo or browse Datasets before connecting a phone. Neither authorizes private reads.

Query through REST

Submit a query to POST /api/v1/queries. Use the JSON arguments from query_phone_data, leaving out requestKey. The OpenAPI specification lists the request and response fields.

Save those arguments in query.json, then send:

curl https://myself.md/api/v1/queries \
  -H "Authorization: Bearer $MYSELF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $QUERY_KEY" \
  --data @query.json

Set QUERY_KEY to a unique value of 1–200 characters. Use the phone, profile and type discovered through MCP.

HTTP 202 means the request was accepted. The response includes requestId, status and expiresAt; the Location header points to GET /api/v1/queries/{requestId}. Set REQUEST_ID to the returned requestId, then poll with the same authorization:

curl "https://myself.md/api/v1/queries/$REQUEST_ID" \
  -H "Authorization: Bearer $MYSELF_TOKEN"
  • queued or running: wait for the phone.
  • complete: read the result page and capture warnings.
  • failed: inspect the error.

Request metadata and results expire after five minutes. Wait for complete before treating a read as successful. REST and MCP share validation, permissions, billing, history and phone execution.

Retry safely

If a response is lost, resend the same arguments with the same Idempotency-Key. A live retry returns the original request without another phone job or billing reservation. Keys are scoped to the account and agent OAuth client.

  • Changing the arguments with the same key fails.
  • Revoked grants or an unavailable original request fail rather than dispatching the old request again.
  • While the original request is initializing, a retry may fail. Check its result before using a new key.

The service retains an activity fingerprint for 90 days to prevent redispatch after a job is forgotten, expires, or the service restarts. Keep keys unique beyond that period. For any write with an uncertain outcome, check its status before retrying with a new identifier.

Validation and permission failures return HTTP 422 with an error. Authentication failures return 401 or 403.

Use the SDK

The JavaScript SDK has no runtime dependencies. Import createMyselfClient from myself-md-sdk, or use the standalone module.

Public methods need no token:

  • health() checks service availability.
  • config() reads public configuration.
  • docs() reads the getting-started guide.
  • datasets({ limit: 1 }) reads a catalog page.

Pass nextCursor as cursor to get the next catalog page. Stop when nextCursor is null and hasMore is false. The catalog describes adapter capabilities; it contains no personal records.

For private queries, create a client with an existing agent token:

import { createMyselfClient } from 'myself-md-sdk';

const myself = createMyselfClient({ token });
const job = await myself.query(input, idempotencyKey);
const status = await myself.request(job.requestId);

Use the discovered query arguments for input and the same retry rules described above. request() reads the current status once; continue polling until the job finishes. For phone results, follow every returned pagination cursor and review capture warnings.

Browsers with WebMCP expose myself_public_documentation and myself_dataset_catalog through document.modelContext, with navigator.modelContext as a compatibility fallback.

Use the CLI

The official CLI requires Node.js 22.13 or later:

npx myself-md-cli help

Or install it globally with npm install --global myself-md-cli and run myself help.

Use health, config, docs and openapi for public reads. tools lists the live MCP schemas; call TOOL reads a JSON argument object from standard input. Private commands need an existing owner-approved OAuth token in MYSELF_TOKEN. MYSELF_URL selects an HTTPS service origin. The CLI does not store tokens or grant access.

A standalone download runs with node myself.mjs help; review the file before running it. Read its dependency notices. The repository source is scripts/myself.js; after installing dependencies, run npm run myself -- help or npm run myself -- call TOOL. Both distributions expose the same public reads and authorized MCP operations. Check get_phone_request to verify that queued phone work completed.

Rate limits

Public OpenAPI reads share a limit of 120 requests per 60 seconds per source IP. REST queries, including polling, have a separate limit of 120 per minute per account and agent client.

These limits apply locally to each Node process or Worker isolate. They are best-effort abuse limits, not global account quotas. Shared networks share a public bucket, and restarting a process resets its window.

Read the response headers to check the current window:

  • RateLimit-Limit: request limit.
  • RateLimit-Remaining: requests left.
  • RateLimit-Reset: seconds until reset.
  • RateLimit-Policy: window policy.

HTTP 429 returns a JSON error and Retry-After in seconds. Wait that long before retrying, and avoid concurrent retries. The X-RateLimit compatibility headers describe the same quota, with the reset expressed in epoch seconds. Private MCP and owner APIs keep their existing authorization and limits.

API versions

Public discovery reads use /v1, such as /v1/health and /v1/config. Unversioned URLs remain aliases for the same contract. Clients should ignore unknown response fields; a breaking change requires a new major path.

Deprecations are announced here at least 90 days before removal. Affected routes return Deprecation and Sunset headers. No v1 route is currently deprecated. MCP negotiates its protocol version separately and uses the live tools/list schemas.

The OpenAPI specification covers public discovery and REST phone queries. The agent catalog links to the MCP server card for connection metadata. These documents expose no private records; discover current private operations through authenticated tools/list.

Privacy and help

Blocking an agent or revoking its grant stops future reads. Copies already delivered to an AI provider follow that provider’s retention policy.

get_privacy_policy returns the shared policy and support contacts under MCP account authentication, without a data grant. Read the privacy policy before sharing sensitive records. myself.md provides data access, not medical advice.

See pricing and common questions for product details, or contact us for help. The source code is public.