Skip to Content
REST APIOverview

API overview

The Skyelight REST API gives scripts and tools access to the threads in your projects over HTTPS. You can list threads, read one with its page, anchor, source location and screenshot, reply to it, assign it, and set its status to open, deferred or resolved.

The API runs the same operations as the Skyelight MCP server. The local MCP package is a client of this API, so a script can do anything an agent can do through MCP.

To connect a coding agent, use MCP. MCP signs you in with OAuth and returns screenshots as images the agent can read. Use the API for scripts, CI jobs and your own tools.

Base URL

https://app.skyelight.ai/api/v1

Request and response bodies are JSON. Send your token as a bearer token in the Authorization header. See Authentication.

Who can use it

The API is one of Skyelight’s agent tools. To use it:

  • You need an owner, admin or collaborator role in the workspace. Reviewers can’t use the API.
  • The workspace’s organization must be on the Pro, Team or Enterprise plan. The Free plan doesn’t include agent tools.

Skyelight checks access for each workspace. If you are a collaborator in one organization and a reviewer in another, the API works in the first and returns the reason it refuses in the second. See Plans and billing and Roles and permissions.

Every call acts as you. Skyelight has no service accounts. A reply posted through the API appears under your name, sends the same notifications as a reply in the app, and reaches only the workspaces your account reaches.

How the data fits together

TermWhat it is
WorkspaceA team’s space, with its members, roles and settings. Access is checked per workspace.
ProjectA body of work in a workspace. Every thread belongs to one project.
ItemA thread: the first message pinned to an element on a page, with its replies. Most endpoints take an item ID.
ReplyA response inside a thread. Endpoints take the thread’s ID, never a reply’s.
Statusopen, deferred (valid work, postponed) or resolved.
TypeA thread’s classification, such as bug, idea or feedback. Each workspace can define its own types.

Timestamps are milliseconds since the Unix epoch (UTC).

Quick start

  1. Create a token

    Go to Account Settings API Keys in the Skyelight web app and create a token. Skyelight shows the token once, so copy it before you close the dialog.

    export SKYELIGHT_API_TOKEN=sky_...

  2. See what you can reach

    curl https://app.skyelight.ai/api/v1/workspaces \
  -H "Authorization: Bearer $SKYELIGHT_API_TOKEN"

    The response lists each workspace, your role in it, and whether agent tools are available there. It also returns your user ID, which you can use as an assignee filter.

  3. Find a project

    curl https://app.skyelight.ai/api/v1/projects \
  -H "Authorization: Bearer $SKYELIGHT_API_TOKEN"

    Projects are sorted by most recent activity, and each has an id.

  4. List open threads

    curl "https://app.skyelight.ai/api/v1/items?projectId=PROJECT_ID&status=open" \
  -H "Authorization: Bearer $SKYELIGHT_API_TOKEN"

    The response starts with a summary of the whole project (totals, and counts by type and by page), then one row per matching thread. To read a thread in full, request /api/v1/items/ITEM_ID with the row’s id.

Calling it from a browser

Every route answers CORS preflight requests, so a web page can call the API. Any code running in the page can read the token it uses. Only call the API from a browser in tools used by the token’s owner.

Next

Last updated on
TroubleshootingAuthentication