{"openapi":"3.1.0","info":{"title":"Terra (BYOK) API","version":"0.1.0","description":"Terra (BYOK) lets an AI assistant read your own Terra data through the Terra API with a key you supply (Terra API key). Read-only: 7 tools (list_connected_users, get_user_info, list_available_integrations, get_activity, get_sleep, get_daily_summary, get_nutrition). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-terra.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-terra/docs"},"termsOfService":"https://connectorbay.com/byok-terra/terms"},"servers":[{"url":"https://byok-terra.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-terra/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_connected_users":{"post":{"operationId":"list_connected_users","summary":"List the user connections in your Terra account (one per connected wearable or app) with provider, your reference ID, cr","description":"List the user connections in your Terra account (one per connected wearable or app) with provider, your reference ID, creation time and active flag. Pages are zero-based; without page every connection is returned. Use for \"Which wearable users are connected to my Terra account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based page number; leave out to get every connection in one answer.","title":"Page"},"per_page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Connections per page (default 500 when paging).","title":"Per Page"}},"title":"list_connected_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_user_info":{"post":{"operationId":"get_user_info","summary":"Look up one connection by Terra user ID: provider, your reference ID, scopes granted, last poll time and most recent dat","description":"Look up one connection by Terra user ID: provider, your reference ID, scopes granted, last poll time and most recent data time. Use for \"When did Terra last receive data for user 5a6b7c8d-1111-4222-8333-444455556666\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Terra user ID (a UUID) of one connected wearable or health-app connection, as returned by list_connected_users.","maxLength":64,"title":"User Id","type":"string"}},"required":["user_id"],"title":"get_user_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_available_integrations":{"post":{"operationId":"list_available_integrations","summary":"List the wearable and health-app integrations Terra supports with display name, setup type, whether it is enabled for yo","description":"List the wearable and health-app integrations Terra supports with display name, setup type, whether it is enabled for your account and which data types (activity, sleep, daily, nutrition, body) each provides. Use for \"Which wearables does Terra support and which are enabled for me\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"sdk":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include integrations that need a mobile SDK (Apple Health, Samsung Health, Health Connect).","title":"Sdk"}},"title":"list_available_integrationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_activity":{"post":{"operationId":"get_activity","summary":"Get completed workouts of one connected user between two dates: name, activity type, start and end time, calories, dista","description":"Get completed workouts of one connected user between two dates: name, activity type, start and end time, calories, distance, steps and heart rate averages. Returned in the answer, no webhook is triggered. Use for \"What workouts did Terra user 5a6b7c8d-1111-4222-8333-444455556666 log in the first week of October\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Terra user ID (a UUID) of one connected wearable or health-app connection, as returned by list_connected_users.","maxLength":64,"title":"User Id","type":"string"},"start_date":{"description":"First day to read, as YYYY-MM-DD or a 10-digit unix timestamp in seconds.","maxLength":20,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to read, as YYYY-MM-DD or a 10-digit unix timestamp (default: one day after the start). A request may span at most 1,825 days.","title":"End Date"},"to_webhook":{"anyOf":[{"const":"false","type":"string"},{"type":"null"}],"default":"false","description":"Always 'false' here: the data is returned in the answer instead of being pushed to your webhook.","title":"To Webhook"}},"required":["user_id","start_date"],"title":"get_activityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_sleep":{"post":{"operationId":"get_sleep","summary":"Get sleep sessions of one connected user between two dates: start and end, nap flag, time asleep, deep, light, REM and a","description":"Get sleep sessions of one connected user between two dates: start and end, nap flag, time asleep, deep, light, REM and awake seconds, efficiency, sleep score, average and resting heart rate and breathing rate. Returned in the answer. Use for \"How did Terra user 5a6b7c8d-1111-4222-8333-444455556666 sleep last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Terra user ID (a UUID) of one connected wearable or health-app connection, as returned by list_connected_users.","maxLength":64,"title":"User Id","type":"string"},"start_date":{"description":"First day to read, as YYYY-MM-DD or a 10-digit unix timestamp in seconds.","maxLength":20,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to read, as YYYY-MM-DD or a 10-digit unix timestamp (default: one day after the start). A request may span at most 1,825 days.","title":"End Date"},"to_webhook":{"anyOf":[{"const":"false","type":"string"},{"type":"null"}],"default":"false","description":"Always 'false' here: the data is returned in the answer instead of being pushed to your webhook.","title":"To Webhook"}},"required":["user_id","start_date"],"title":"get_sleepArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_daily_summary":{"post":{"operationId":"get_daily_summary","summary":"Get day-level summaries of one connected user between two dates: steps, distance, floors, calories burned, active second","description":"Get day-level summaries of one connected user between two dates: steps, distance, floors, calories burned, active seconds, heart rate and the provider's activity, recovery and sleep scores. Returned in the answer. Use for \"How many steps did Terra user 5a6b7c8d-1111-4222-8333-444455556666 take each day this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Terra user ID (a UUID) of one connected wearable or health-app connection, as returned by list_connected_users.","maxLength":64,"title":"User Id","type":"string"},"start_date":{"description":"First day to read, as YYYY-MM-DD or a 10-digit unix timestamp in seconds.","maxLength":20,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to read, as YYYY-MM-DD or a 10-digit unix timestamp (default: one day after the start). A request may span at most 1,825 days.","title":"End Date"},"to_webhook":{"anyOf":[{"const":"false","type":"string"},{"type":"null"}],"default":"false","description":"Always 'false' here: the data is returned in the answer instead of being pushed to your webhook.","title":"To Webhook"}},"required":["user_id","start_date"],"title":"get_daily_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nutrition":{"post":{"operationId":"get_nutrition","summary":"Get food and drink logs of one connected user between two dates: daily calories, protein, carbohydrates, fat, fibre, sug","description":"Get food and drink logs of one connected user between two dates: daily calories, protein, carbohydrates, fat, fibre, sugar, sodium, water and the logged meals. Only providers that sync nutrition (for example food-logging apps) return data. Use for \"What did Terra user 5a6b7c8d-1111-4222-8333-444455556666 eat on 2026-10-02\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"user_id":{"description":"Terra user ID (a UUID) of one connected wearable or health-app connection, as returned by list_connected_users.","maxLength":64,"title":"User Id","type":"string"},"start_date":{"description":"First day to read, as YYYY-MM-DD or a 10-digit unix timestamp in seconds.","maxLength":20,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Last day to read, as YYYY-MM-DD or a 10-digit unix timestamp (default: one day after the start). A request may span at most 1,825 days.","title":"End Date"},"to_webhook":{"anyOf":[{"const":"false","type":"string"},{"type":"null"}],"default":"false","description":"Always 'false' here: the data is returned in the answer instead of being pushed to your webhook.","title":"To Webhook"}},"required":["user_id","start_date"],"title":"get_nutritionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}