{"openapi":"3.1.0","info":{"title":"Obelism numbers agent API","version":"1","description":"Read a space's visitors, pages, sources and events. Every operation reads; nothing changes. Sign in on www (its agent API) for a session token, or connect the MCP server at /mcp with OAuth."},"servers":[{"url":"https://numbers.obelism.studio"}],"paths":{"/api/agent/organizations":{"get":{"operationId":"listOrganizations","summary":"Your organizations that use numbers","description":"Your organizations that use numbers. Every organization that uses improve or Content has numbers, seen by every member an admin did not keep out of it.","security":[{"sessionToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"organizationId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"role":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or expired token.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"404":{"description":"No such organization, space or environment of yours.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"429":{"description":"Over 300 requests a minute.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}}}}},"/api/agent/organizations/{organizationId}/spaces":{"get":{"operationId":"listSpaces","summary":"The spaces of an organization you may open","description":"The spaces of an organization you may open. A space is a site: improve's tests and Content's pages of a space send their events to its numbers.","security":[{"sessionToken":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"description":"From listOrganizations.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"spaces":{"type":"array","items":{"type":"object","properties":{"spaceId":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or expired token.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"404":{"description":"No such organization, space or environment of yours.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"429":{"description":"Over 300 requests a minute.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/{environment}/report":{"get":{"operationId":"getReport","summary":"A space environment's visitors, pages, sources, campaigns, countries, devices and clicked elements","description":"A space environment's visitors, pages, sources, campaigns, countries, devices and clicked elements. What the dashboard overview shows: totals (with `previous`, the range before, to compare), visitors, sessions and page views per bucket (UTC hours or days), and the top 10 of each breakdown. Sources are referrer hosts, \"direct\" without one. Clicked elements are the ones a site tags with `data-numbers-id` (in Content, a block's `_uid`).","security":[{"sessionToken":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"description":"From listOrganizations.","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"From listSpaces.","schema":{"type":"string"}},{"name":"environment","in":"path","required":true,"description":"Production unless the user says otherwise.","schema":{"type":"string","enum":["develop","staging","production"]}},{"name":"range","in":"query","description":"How far back: 24h (by hour), 7d (default), 30d or 90d (by day).","schema":{"type":"string","enum":["24h","7d","30d","90d"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string"},"totals":{"type":"object","properties":{"visitors":{"type":"integer"},"pageViews":{"type":"integer"},"events":{"type":"integer"},"sessions":{"type":"integer"},"bounceRate":{"type":"number","description":"Of the sessions with a page view, the share with that one page view and nothing else, 0–1."},"averageSeconds":{"type":"number","description":"A session ends after 30 minutes without an event."},"previous":{"type":"object","properties":{"visitors":{"type":"integer"},"pageViews":{"type":"integer"},"events":{"type":"integer"},"sessions":{"type":"integer"},"bounceRate":{"type":"number","description":"Of the sessions with a page view, the share with that one page view and nothing else, 0–1."},"averageSeconds":{"type":"number","description":"A session ends after 30 minutes without an event."}}}}},"series":{"type":"array","items":{"type":"object","properties":{"bucket":{"type":"string","description":"ISO start of the hour or day."},"visitors":{"type":"integer"},"sessions":{"type":"integer"},"pageViews":{"type":"integer"}}}},"pages":{"type":"array","items":{"type":"object","properties":{"page":{"type":"string"},"views":{"type":"integer"},"visitors":{"type":"integer"}}}},"sources":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"visitors":{"type":"integer"}}}},"campaigns":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"medium":{"type":"string"},"campaign":{"type":"string"},"visitors":{"type":"integer"}}}},"countries":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"visitors":{"type":"integer"}}}},"devices":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"visitors":{"type":"integer"}}}},"browsers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"visitors":{"type":"integer"}}}},"systems":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"visitors":{"type":"integer"}}}},"elements":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"clicks":{"type":"integer"},"clickers":{"type":"integer","description":"Visitors who clicked it."},"viewers":{"type":"integer","description":"Visitors who saw a page it was clicked on."},"rate":{"type":"number","description":"clickers / viewers."}}}}}}}}},"401":{"description":"Missing, invalid or expired token.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"404":{"description":"No such organization, space or environment of yours.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"429":{"description":"Over 300 requests a minute.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/{environment}/events":{"get":{"operationId":"listEvents","summary":"The events a space environment received, most frequent first","description":"The events a space environment received, most frequent first. Each event name with its scope (a test's or flag's slug, a clicked element's id), how often it came in, from how many visitors, and when last. Shows what a site sends, and whether a test's goal events arrive.","security":[{"sessionToken":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"description":"From listOrganizations.","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"From listSpaces.","schema":{"type":"string"}},{"name":"environment","in":"path","required":true,"description":"Production unless the user says otherwise.","schema":{"type":"string","enum":["develop","staging","production"]}},{"name":"range","in":"query","description":"How far back: 24h (by hour), 7d (default), 30d or 90d (by day).","schema":{"type":"string","enum":["24h","7d","30d","90d"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"range":{"type":"string"},"events":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string"},"scope":{"type":"string"},"count":{"type":"integer"},"visitors":{"type":"integer"},"lastSeen":{"type":"string"}}}}}}}}},"401":{"description":"Missing, invalid or expired token.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"404":{"description":"No such organization, space or environment of yours.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}},"429":{"description":"Over 300 requests a minute.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string"}}}}}}}}}},"components":{"securitySchemes":{"sessionToken":{"type":"http","scheme":"bearer","description":"A session token from www's agent API (POST /api/agent/auth/sign-in)."}}}}