{"openapi":"3.1.0","info":{"title":"Hologram (BYOK) API","version":"0.1.0","description":"Hologram (BYOK) lets an AI assistant read your own Hologram data through the Hologram API with a key you supply (REST API key). Read-only: 12 tools (list_sims, get_sim, get_sim_count, list_tags, list_open_sessions, list_data_usage_records, list_daily_data_usage, list_monthly_data_usage, get_total_data_usage, list_plans, list_organizations, get_organization_balance). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hologram.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hologram/docs"},"termsOfService":"https://connectorbay.com/byok-hologram/terms"},"servers":[{"url":"https://byok-hologram.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hologram/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_sims":{"post":{"operationId":"list_sims","summary":"List SIMs (called devices by Hologram), newest first, with name, state, plan, tags and model. Page with startafter set t","description":"List SIMs (called devices by Hologram), newest first, with name, state, plan, tags and model. Page with startafter set to lastid while continues is true. Use for \"Which Hologram SIMs are live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 5000).","title":"Limit"},"startafter":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor: return SIMs after this id (use lastid from the previous answer).","title":"Startafter"},"orgid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records of this organization ID; leave empty for the key's own organization.","title":"Orgid"},"states":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated network states to keep, for example 'LIVE,FROZEN'.","title":"States"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only SIMs whose name equals this.","title":"Name"},"tagid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only SIMs with this tag id.","title":"Tagid"}},"title":"list_simsArguments","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_sim":{"post":{"operationId":"get_sim","summary":"Get one SIM by its device id: name, state, plan, tags, model and creation date. Use for \"Show Hologram SIM 56668\".","description":"Get one SIM by its device id: name, state, plan, tags, model and creation date. Use for \"Show Hologram SIM 56668\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Hologram device (SIM) id.","title":"Device Id","type":"integer"}},"required":["device_id"],"title":"get_simArguments","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_sim_count":{"post":{"operationId":"get_sim_count","summary":"Count SIMs, optionally by state, tag or organization. Use for \"How many Hologram SIMs are live\".","description":"Count SIMs, optionally by state, tag or organization. Use for \"How many Hologram SIMs are live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"orgid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records of this organization ID; leave empty for the key's own organization.","title":"Orgid"},"tagids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated device tag ids to filter by.","title":"Tagids"},"states":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated network states to count, for example 'LIVE'.","title":"States"}},"title":"get_sim_countArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List the device tags in the organization, optionally for chosen devices. Use for \"What device tags do I use in Hologram\"","description":"List the device tags in the organization, optionally for chosen devices. Use for \"What device tags do I use in Hologram\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"orgid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records of this organization ID; leave empty for the key's own organization.","title":"Orgid"},"deviceids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated device ids to limit the tags to.","title":"Deviceids"}},"title":"list_tagsArguments","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_open_sessions":{"post":{"operationId":"list_open_sessions","summary":"List the ids of SIMs that currently have an open cellular data session. Use for \"Which Hologram SIMs are online right no","description":"List the ids of SIMs that currently have an open cellular data session. Use for \"Which Hologram SIMs are online right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"orgid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records of this organization ID; leave empty for the key's own organization.","title":"Orgid"}},"title":"list_open_sessionsArguments","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_data_usage_records":{"post":{"operationId":"list_data_usage_records","summary":"List recent per-session data usage records (bytes, time, network, radio technology) with cursor paging. Use for \"Show re","description":"List recent per-session data usage records (bytes, time, network, radio technology) with cursor paging. Use for \"Show recent Hologram data sessions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 5000).","title":"Limit"},"before":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor: records with id lower than this.","title":"Before"},"after":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor: records with id higher than this.","title":"After"},"linkids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SIM profile (link) ids to filter by.","title":"Linkids"},"tagids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated device tag ids to filter by.","title":"Tagids"},"timestart":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records from this Unix time (seconds) onward.","title":"Timestart"},"timeend":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records up to this Unix time (seconds).","title":"Timeend"}},"title":"list_data_usage_recordsArguments","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_daily_data_usage":{"post":{"operationId":"list_daily_data_usage","summary":"List data usage aggregated per SIM profile and day: bytes, sessions and reporting windows. Set aggregateall to true for ","description":"List data usage aggregated per SIM profile and day: bytes, sessions and reporting windows. Set aggregateall to true for one summed row. Use for \"How much data did my Hologram SIMs use per day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 5000).","title":"Limit"},"linkids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SIM profile (link) ids to filter by.","title":"Linkids"},"tagids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated device tag ids to filter by.","title":"Tagids"},"timestart":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records from this Unix time (seconds) onward.","title":"Timestart"},"timeend":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records up to this Unix time (seconds).","title":"Timeend"},"aggregateall":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to sum all matching records into one row.","title":"Aggregateall"}},"title":"list_daily_data_usageArguments","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_monthly_data_usage":{"post":{"operationId":"list_monthly_data_usage","summary":"List data usage aggregated per SIM profile and month: bytes and sessions. Use for \"How much data did my Hologram SIMs us","description":"List data usage aggregated per SIM profile and month: bytes and sessions. Use for \"How much data did my Hologram SIMs use each month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 5000).","title":"Limit"},"linkids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated SIM profile (link) ids to filter by.","title":"Linkids"},"tagids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated device tag ids to filter by.","title":"Tagids"},"timestart":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records from this Unix time (seconds) onward.","title":"Timestart"},"timeend":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records up to this Unix time (seconds).","title":"Timeend"},"aggregateall":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to sum all matching records into one row.","title":"Aggregateall"}},"title":"list_monthly_data_usageArguments","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_total_data_usage":{"post":{"operationId":"get_total_data_usage","summary":"Get total bytes, sessions and reporting windows across all SIMs for a time range. Use for \"What is my total Hologram dat","description":"Get total bytes, sessions and reporting windows across all SIMs for a time range. Use for \"What is my total Hologram data usage this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"timestart":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records from this Unix time (seconds) onward.","title":"Timestart"},"timeend":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records up to this Unix time (seconds).","title":"Timeend"}},"title":"get_total_data_usageArguments","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_plans":{"post":{"operationId":"list_plans","summary":"List data plans available to the organization with data allowance, billing period, category and whether enabled. Use for","description":"List data plans available to the organization with data allowance, billing period, category and whether enabled. Use for \"Which Hologram data plans can I use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 1000).","title":"Limit"},"startafter":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Cursor: return plans after this id.","title":"Startafter"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only plans whose name contains this text.","title":"Name"},"orgid":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only records of this organization ID; leave empty for the key's own organization.","title":"Orgid"}},"title":"list_plansArguments","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_organizations":{"post":{"operationId":"list_organizations","summary":"List organizations the key can see, with id, name, plan flag and whether personal (member lists are not returned). Use f","description":"List organizations the key can see, with id, name, plan flag and whether personal (member lists are not returned). Use for \"Which Hologram organizations do I belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records to return (1 to 1000).","title":"Limit"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only organizations whose name contains this text.","title":"Q"}},"title":"list_organizationsArguments","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_organization_balance":{"post":{"operationId":"get_organization_balance","summary":"Get an organization's prepaid account balance, promo balance and pending charges. Use for \"What is my Hologram account b","description":"Get an organization's prepaid account balance, promo balance and pending charges. Use for \"What is my Hologram account balance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_id":{"description":"Organization id (list_organizations returns it).","title":"Org Id","type":"integer"}},"required":["org_id"],"title":"get_organization_balanceArguments","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}}}}