Worlds / Eng and it ops

Jira API

A local Jira with projects, issues, workflows, transitions, sprints and boards. Test the agent that triages, transitions and plans issues, and see every field and status it changed.

Base path: /rest/api/3
Auth: OAuth bearer token, or email and API token over basic auth, the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Jira world serves in the closed beta. Paths mirror the public Jira 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_JIRA_URL`	This world's origin followed by `/rest/api/3`
`WORLDS_API_KEY`	The world key, accepted wherever Jira expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · jira.js

import { Version3Client } from "jira.js";

const client = new Version3Client({
  host: process.env.WORLDS_JIRA_URL,
  authentication: { oauth2: { accessToken: process.env.WORLDS_API_KEY } },
});

const results = await client.issueSearch.searchForIssuesUsingJql({
  jql: "project = ACME AND status = Open",
});

API reference

18 of 18

Issues

Tickets with type, status, assignee and custom fields.

POST/rest/api/3/issueCreate an issue
GET/rest/api/3/issue/{issueIdOrKey}Get an issue
PUT/rest/api/3/issue/{issueIdOrKey}Edit an issue
DELETE/rest/api/3/issue/{issueIdOrKey}Delete an issue
PUT/rest/api/3/issue/{issueIdOrKey}/assigneeAssign an issue
POST/rest/api/3/issue/{issueIdOrKey}/commentAdd a comment

Fields · 6

`id`	string	Issue id
`key`	string	Issue key such as ACME-12
`fields.summary`	string	Summary
`fields.status`	object	Workflow status
`fields.assignee`	object	Assignee
`fields.priority`	object	Priority

Search

JQL queries over issues.

GET/rest/api/3/searchSearch for issues with JQL
POST/rest/api/3/searchSearch for issues with JQL in a body
GET/rest/api/3/jql/autocompletedataGet JQL field names

Fields · 5

`jql`	string	The query
`maxResults`	integer	Page size
`startAt`	integer	Page offset
`total`	integer	Total matches
`issues`	array	Matching issues

Transitions

Workflow moves available for an issue.

GET/rest/api/3/issue/{issueIdOrKey}/transitionsList available transitions
POST/rest/api/3/issue/{issueIdOrKey}/transitionsTransition an issue
GET/rest/api/3/statusList all statuses

Fields · 4

`id`	string	Transition id
`name`	string	Transition name
`to`	object	Target status
`hasScreen`	boolean	Whether a screen is required

Projects

Projects, their components and versions.

GET/rest/api/3/project/searchSearch projects
GET/rest/api/3/project/{projectIdOrKey}Get a project
GET/rest/api/3/project/{projectIdOrKey}/componentsList project components

Fields · 5

`id`	string	Project id
`key`	string	Project key
`name`	string	Project name
`projectTypeKey`	string	software, business or service_desk
`lead`	object	Project lead

Users

Account lookup for assignment and mentions.

GET/rest/api/3/user/searchFind users
GET/rest/api/3/userGet a user by account id
GET/rest/api/3/myselfGet the current user

Fields · 4

`accountId`	string	Account id
`displayName`	string	Display name
`emailAddress`	string	Email address
`active`	boolean	Whether the account is active

Test workflow

Prepare. Select the Jira setup for your workflow and review its starting records, including issues, search, transitions.
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

PAY-211 in In Review
PAY-205 Done with resolution Fixed
PAY-212 still In Review
No issues added to the closed sprint
WEB project unchanged

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 · Jira
version: 2
connector: jira
seed: jira-starter
mode: isolated
policy: >
  Update Sprint 42 on the PAY board. Move issues with merged PRs to In Review
  and approved reviews to Done with resolution Fixed. Leave anything with an
  open review where it is.
tasks:
  - id: transition-issues-when-linked-work-is-done
    prompt: Transition issues when linked work is done
  - id: move-issues-into-the-active-sprint
    prompt: Move issues into the active sprint
  - id: triage-new-bugs-with-priority-component-and-assignee
    prompt: "Triage new bugs with priority, component and assignee"
expected:
  - PAY-211 in In Review
  - PAY-205 Done with resolution Fixed
  - PAY-212 still In Review
  - No issues added to the closed sprint
  - WEB project unchanged
scenarios:
  - required-field
  - rate-limited
  - invalid-transition

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
`required-field`	The Done transition returns 400 until resolution is set
`rate-limited`	The REST API returns 429 with Retry-After
`invalid-transition`	A transition id not available from the current status is rejected
`permission-denied`	The bot user cannot transition WEB issues
`webhook-twice`	jira:issue_updated arrives two times

Starting data

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

Records	Starting setup
projects	PAY and WEB, each with its own workflow
issues	150 stories, bugs and subtasks with links
sprints	One active, one future and one closed sprint
workflows	To Do, In Progress, In Review and Done with transition screens
components	Checkout, Billing, Auth with default assignees

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

Tickets with type, status, assignee and custom fields.

Field	Type	Meaning / relationship
`id`	string	Issue id
`key`	string	Issue key such as ACME-12
`fields.summary`	string	Summary
`fields.status`	object	Workflow status
`fields.assignee`	object	Assignee
`fields.priority`	object	Priority

json · illustrative record shape

{
  "id": "<Issue id>",
  "key": "<Issue key such as ACME-12>",
  "fields.summary": "<Summary>",
  "fields.status": {},
  "fields.assignee": {},
  "fields.priority": {}
}

See issues operations

Search records

Search

JQL queries over issues.

Field	Type	Meaning / relationship
`jql`	string	The query
`maxResults`	integer	Page size
`startAt`	integer	Page offset
`total`	integer	Total matches
`issues`	array	Matching issues

json · illustrative record shape

{
  "jql": "<The query>",
  "maxResults": 1,
  "startAt": 1,
  "total": 1,
  "issues": []
}

See search operations

Transitions records

Transitions

Workflow moves available for an issue.

Field	Type	Meaning / relationship
`id`	string	Transition id
`name`	string	Transition name
`to`	object	Target status
`hasScreen`	boolean	Whether a screen is required

json · illustrative record shape

{
  "id": "<Transition id>",
  "name": "<Transition name>",
  "to": {},
  "hasScreen": false
}

See transitions operations

Projects records

Projects

Projects, their components and versions.

Field	Type	Meaning / relationship
`id`	string	Project id
`key`	string	Project key
`name`	string	Project name
`projectTypeKey`	string	software, business or service_desk
`lead`	object	Project lead

json · illustrative record shape

{
  "id": "<Project id>",
  "key": "<Project key>",
  "name": "<Project name>",
  "projectTypeKey": "<software, business or service_desk>",
  "lead": {}
}

See projects operations

Users records

Users

Account lookup for assignment and mentions.

Field	Type	Meaning / relationship
`accountId`	string	Account id
`displayName`	string	Display name
`emailAddress`	string	Email address
`active`	boolean	Whether the account is active

json · illustrative record shape

{
  "accountId": "<Account id>",
  "displayName": "<Display name>",
  "emailAddress": "person@example.test",
  "active": false
}

See users operations

See the Jira world in the catalog