Worlds / Eng and it ops

Linear API

A local Linear workspace with teams, issues, workflow states, cycles, projects and labels. Test the agent that triages incoming issues, sets priority and plans cycles.

Base path: /graphql
Auth: API key or OAuth bearer token, the world key
Endpoints: 14
Status: Active today

This reference previews the surface the Linear world serves in the closed beta. Paths mirror the public Linear API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_LINEAR_URL`	This world's origin followed by `/graphql`
`WORLDS_API_KEY`	The world key, accepted wherever Linear expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @linear/sdk

import { LinearClient } from "@linear/sdk";

const linear = new LinearClient({
  apiKey: process.env.WORLDS_API_KEY,
  apiUrl: process.env.WORLDS_LINEAR_URL + "/graphql",
});

const issues = await linear.issues({ first: 20 });

API reference

14 of 14

Issues

Work items with state, priority, assignee and labels.

POST/graphql/graphql · issuesList issues
POST/graphql/graphql · issueGet an issue
POST/graphql/graphql · issueCreateCreate an issue
POST/graphql/graphql · issueUpdateUpdate an issue
POST/graphql/graphql · commentCreateComment on an issue

Fields · 6

`id`	ID	Issue id
`identifier`	String	Key such as ENG-42
`title`	String	Title
`state`	WorkflowState	Workflow state
`priority`	Int	0 none through 4 low
`assignee`	User	Assignee

Teams

Teams that own issues, cycles and workflow states.

POST/graphql/graphql · teamsList teams
POST/graphql/graphql · teamGet a team
POST/graphql/graphql · workflowStatesList workflow states

Fields · 4

`id`	ID	Team id
`key`	String	Team key
`name`	String	Team name
`states`	Connection	Workflow states

Projects

Projects that group issues toward a goal.

POST/graphql/graphql · projectsList projects
POST/graphql/graphql · projectCreateCreate a project
POST/graphql/graphql · projectUpdateUpdate a project

Fields · 5

`id`	ID	Project id
`name`	String	Name
`state`	String	planned, started, completed and more
`targetDate`	Date	Target date
`lead`	User	Project lead

Cycles

Time boxed sprints for a team.

POST/graphql/graphql · cyclesList cycles
POST/graphql/graphql · cycleGet a cycle
POST/graphql/graphql · cycleCreateCreate a cycle

Fields · 5

`id`	ID	Cycle id
`number`	Float	Cycle number
`startsAt`	DateTime	Start
`endsAt`	DateTime	End
`progress`	Float	Share of scope completed

Test workflow

Prepare. Select the Linear setup for your workflow and review its starting records, including issues, teams, projects.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

ENG-1402 in Todo with priority High
ENG-1405 marked duplicate of ENG-1402
ENG-1407 still in Triage or accepted
Customer labels unchanged
Current cycle scope grows by one issue

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Linear
version: 2
connector: linear
seed: linear-starter
mode: isolated
policy: >
  Clear ENG Triage. Accept real bugs into Todo with priority, mark true
  duplicates as duplicates of the original, and never cancel anything labeled
  Customer and Urgent.
tasks:
  - id: accept-or-decline-issues-in-triage
    prompt: Accept or decline issues in Triage
  - id: mark-duplicates-and-merge-context
    prompt: Mark duplicates and merge context
  - id: assign-issues-to-the-current-cycle-by-priority
    prompt: Assign issues to the current cycle by priority
expected:
  - ENG-1402 in Todo with priority High
  - ENG-1405 marked duplicate of ENG-1402
  - ENG-1407 still in Triage or accepted
  - Customer labels unchanged
  - Current cycle scope grows by one issue
scenarios:
  - rate-limited
  - complexity-limit
  - key-revoked

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	GraphQL returns a RATELIMITED error
`complexity-limit`	A large query exceeds the complexity budget
`key-revoked`	The API key is revoked and requests fail authentication
`webhook-twice`	The Issue update webhook arrives two times

Starting data

Start each run from the same records and relationships. The overview below describes the Linear starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
teams	ENG and DES with their own workflow states
issues	180 across Triage, Backlog, Todo, In Progress and Done
cycles	Current and next cycle with scope
projects	4 projects with leads and target dates
labels	Bug, Feature, Customer and area labels

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Issues records

Issues

Work items with state, priority, assignee and labels.

Field	Type	Meaning / relationship
`id`	ID	Issue id
`identifier`	String	Key such as ENG-42
`title`	String	Title
`state`	WorkflowState	Workflow state
`priority`	Int	0 none through 4 low
`assignee`	User	Assignee

json · illustrative record shape

{
  "id": "<Issue id>",
  "identifier": "<Key such as ENG-42>",
  "title": "<Title>",
  "state": "<Workflow state>",
  "priority": 1,
  "assignee": "<Assignee>"
}

See issues operations

Teams records

Teams

Teams that own issues, cycles and workflow states.

Field	Type	Meaning / relationship
`id`	ID	Team id
`key`	String	Team key
`name`	String	Team name
`states`	Connection	Workflow states

json · illustrative record shape

{
  "id": "<Team id>",
  "key": "<Team key>",
  "name": "<Team name>",
  "states": "<Workflow states>"
}

See teams operations

Projects records

Projects

Projects that group issues toward a goal.

Field	Type	Meaning / relationship
`id`	ID	Project id
`name`	String	Name
`state`	String	planned, started, completed and more
`targetDate`	Date	Target date
`lead`	User	Project lead

json · illustrative record shape

{
  "id": "<Project id>",
  "name": "<Name>",
  "state": "<planned, started, completed and more>",
  "targetDate": "<Target date>",
  "lead": "<Project lead>"
}

See projects operations

Cycles records

Cycles

Time boxed sprints for a team.

Field	Type	Meaning / relationship
`id`	ID	Cycle id
`number`	Float	Cycle number
`startsAt`	DateTime	Start
`endsAt`	DateTime	End
`progress`	Float	Share of scope completed

json · illustrative record shape

{
  "id": "<Cycle id>",
  "number": 1,
  "startsAt": "<Start>",
  "endsAt": "<End>",
  "progress": 1
}

See cycles operations

See the Linear world in the catalog