{"openapi":"3.1.1","info":{"title":"myself.md public discovery API","version":"1.0.0","description":"Public service discovery and authenticated asynchronous phone queries. Additional private account and phone operations are exposed through OAuth-protected MCP at /mcp; initialize and call tools/list for authoritative schemas. This specification does not describe private dashboard or phone-owner APIs. Public reads are versioned under /v1. Additive fields are compatible; breaking changes require a new major path. Deprecations are announced in /docs at least 90 days before removal, with Deprecation and Sunset response headers. No v1 endpoint is currently deprecated.","contact":{"name":"myself.md support","email":"cody@isolated.tech","url":"https://myself.md/contact"}},"servers":[{"url":"https://myself.md"}],"externalDocs":{"description":"MCP authentication and owner approval workflow","url":"https://myself.md/docs"},"components":{"securitySchemes":{"agentBearer":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.0 access token","description":"Agent OAuth client, myselfmd scope and owner-approved phone data grants required. Discover the issuer at /.well-known/oauth-protected-resource/mcp."}},"schemas":{"ServiceError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Safe human-readable failure message; contains no credentials."}}}}},"paths":{"/v1/dataset-catalog":{"get":{"operationId":"listPublicDatasets","summary":"List supported dataset adapters; follow nextCursor until hasMore is false. No personal records.","description":"List supported dataset adapters; follow nextCursor until hasMore is false. No personal records.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["items","nextCursor","hasMore","total"],"properties":{"items":{"type":"array","items":{"type":"object","required":["slug","name","domain","description","url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"sources":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"object","required":["title","keys"],"properties":{"title":{"type":"string"},"keys":{"type":"array","items":{"type":"string"}}}}}}}},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"total":{"type":"integer"}}}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":3,"default":3}},{"name":"cursor","in":"query","schema":{"type":"string","pattern":"^catalog-v1:[0-3]$"}}]}},"/api/v1/queries":{"post":{"operationId":"createPhoneQuery","summary":"Queue an owner-approved phone query. Poll the Location URL for the actual result.","security":[{"agentBearer":[]}],"description":"Idempotency keys are scoped to account and agent client. Identical live retries reuse the job without another billing reservation. Changed arguments, unavailable originals and revoked grants fail. Jobs expire after five minutes; activity fingerprints are retained for 90 days. A 202 response does not prove completion.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deviceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Owned phone UUID returned by list_connected_phones. Use get_phone_data_catalog to check its current connectivity and grants."},"profileId":{"type":"string","minLength":1,"maxLength":100,"description":"Existing profile ID returned by get_phone_data_catalog; query access requires agentAccess and the relevant data permission."},"domain":{"type":"string","enum":["health","time","location"],"description":"Data domain from get_phone_data_catalog. The chosen profile and phone-wide grant must both permit it."},"type":{"type":"string","minLength":1,"maxLength":160,"description":"Exact native type identifier from the selected catalog domain, without the native: prefix. Do not invent type names."},"source":{"default":"native","description":"Capture adapter; native reads data through the phone's operating-system APIs under existing OS permissions.","type":"string","const":"native"},"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Inclusive start of the query interval as a UTC ISO 8601 timestamp. The positive interval must be at most 31 days."},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"End of the query interval as a UTC ISO 8601 timestamp, later than start and no more than 31 days after it."},"cursor":{"default":"","description":"Pagination cursor returned by the preceding response. Omit for the first page; preserve the other query arguments when continuing.","type":"string","maxLength":16000},"limit":{"default":50,"description":"Maximum records in this page, up to 50. Follow the returned nextCursor to continue.","type":"integer","minimum":1,"maximum":50},"format":{"default":"json","description":"Response serialization format; JSON returns structured records and JSONL returns one serialized record per line.","type":"string","enum":["json","jsonl"]},"schema":{"default":"myself.md.export.v1","description":"Export schema version from list_export_schemas; omit to use the released default version.","type":"string","enum":["myself.md.export.v1"]}},"required":["deviceId","profileId","domain","type","start","end"]}}}},"responses":{"202":{"description":"Query accepted, or original live query returned.","headers":{"Location":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["requestId","status","expiresAt"],"properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"expiresAt":{"type":"integer","description":"Unix epoch milliseconds."}}}}}},"401":{"description":"Missing or expired OAuth token."},"403":{"description":"Invalid scope, blocked agent or first-party client."},"422":{"description":"Input, grant, billing, idempotency or phone availability failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"429":{"description":"Agent REST local quota exceeded; honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}}}}}},"/api/v1/queries/{requestId}":{"get":{"operationId":"getPhoneQuery","summary":"Poll the actual phone query state and completed page.","security":[{"agentBearer":[]}],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current query state; queued and running require continued polling.","content":{"application/json":{"schema":{"type":"object","required":["requestId","status","expiresAt","result","error"],"properties":{"requestId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"expiresAt":{"type":"integer"},"result":{"type":["object","null"],"description":"Completed export page, schema and format. Follow result.page.nextCursor with a new query."},"error":{"type":["string","null"]}}}}}},"401":{"description":"Missing or expired OAuth token."},"403":{"description":"Invalid scope, blocked agent or first-party client."},"422":{"description":"Unknown, expired or inaccessible request."}}}},"/v1/health":{"get":{"operationId":"getServiceHealth","summary":"Check whether the hosted service can respond. Does not prove phone availability.","description":"Check whether the hosted service can respond. Does not prove phone availability.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"platform":{"type":"string","description":"Present on the hosted Worker."}}}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/dashboard/config":{"get":{"operationId":"getDashboardConnectionConfiguration","summary":"Discover the OAuth issuer and dashboard client ID. Sign-in and owner authorization remain required for dashboard actions.","description":"Discover the OAuth issuer and dashboard client ID. Sign-in and owner authorization remain required for dashboard actions.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["issuer","clientId"],"properties":{"issuer":{"type":"string","format":"uri"},"clientId":{"type":"string"}}}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/config":{"get":{"operationId":"getConnectionConfiguration","summary":"Discover the OAuth issuer, phone client ID and MCP resource URL.","description":"Discover the OAuth issuer, phone client ID and MCP resource URL.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["issuer","clientId","resource"],"properties":{"issuer":{"type":"string","format":"uri"},"clientId":{"type":"string"},"resource":{"type":"string","format":"uri"}}}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"getMcpProtectedResource","summary":"Discover OAuth authorization servers and scopes for the MCP resource.","description":"Discover OAuth authorization servers and scopes for the MCP resource.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["resource","authorization_servers","scopes_supported","bearer_methods_supported"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}}}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/llms.txt":{"get":{"operationId":"getAgentInstructions","summary":"Read public guidance on when to use myself.md and where to find developer resources.","description":"Read public guidance on when to use myself.md and where to find developer resources.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/docs/reference":{"get":{"operationId":"getApiReference","summary":"Read detailed authentication, safe retries, pagination, asynchronous query and API compatibility rules. Send Accept: text/markdown.","description":"Read detailed authentication, safe retries, pagination, asynchronous query and API compatibility rules. Send Accept: text/markdown.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"text/markdown":{"schema":{"type":"string","description":"Public Markdown content; no personal records."}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}},"/v1/docs":{"get":{"operationId":"getDeveloperGuide","summary":"Read MCP onboarding, authentication, consent and result verification guidance. Send Accept: text/markdown to request the documented Markdown representation.","description":"Read MCP onboarding, authentication, consent and result verification guidance. Send Accept: text/markdown to request the documented Markdown representation.","security":[],"responses":{"200":{"description":"Public read completed.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"text/markdown":{"schema":{"type":"string","description":"Public Markdown content; no personal records."}}}},"429":{"description":"Public read rate limit exceeded. Honor Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}},"503":{"description":"Service could not complete the request; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceError"}}}}}}}}}