Skip to main content
Issue dependencies express relationships between issues to track blocking, related, and duplicate connections in your project.

Quick Start

1

Create a Dependency

Link one issue to another with a specific relationship type:
TOKEN="your-jwt-token"
WS_ID="workspace-id"
ISSUE_ID="issue-id"

curl -s -X POST http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/dependencies/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"depends_on_issue_id":"OTHER_ISSUE_ID","type":"blocks"}' \
  --max-time 10
2

List Dependencies

View all dependencies for an issue:
curl -s http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/dependencies/ \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10
3

Delete a Dependency

Remove a dependency by its ID:
curl -s -X DELETE http://localhost:8000/api/v1/workspaces/$WS_ID/issues/$ISSUE_ID/dependencies/DEP_ID \
  -H "Authorization: Bearer $TOKEN" \
  --max-time 10

How It Works

Dependencies are bidirectional - when you create a relationship between Issue A and Issue B, the dependency appears when listing from either issue.
OperationMethodPurpose
CreatePOSTEstablish new dependency link
ListGETView all dependencies for an issue
DeleteDELETERemove specific dependency

Configuration Options

API Endpoints

MethodEndpointDescription
POST/api/v1/workspaces/{ws_id}/issues/{issue_id}/dependencies/Create dependency
GET/api/v1/workspaces/{ws_id}/issues/{issue_id}/dependencies/List dependencies
DELETE/api/v1/workspaces/{ws_id}/issues/{issue_id}/dependencies/{dep_id}Delete dependency

Request Schema

Create Dependency:
{
  "depends_on_issue_id": "issue-def456",
  "type": "blocks"
}
Response:
{
  "id": "dep-abc123",
  "issue_id": "issue-abc123",
  "depends_on_issue_id": "issue-def456",
  "type": "blocks"
}

Dependency Types

TypeMeaningUse Case
blocksThis issue blocks the other issueIssue A must be resolved before Issue B can proceed
relatedIssues are related but not blockingSimilar topics or shared components
duplicatesThis issue is a duplicate of the otherSame problem reported multiple times

Common Patterns

import asyncio
import httpx

async def main():
    base = "http://localhost:8000/api/v1"
    headers = {"Authorization": "Bearer YOUR_TOKEN", "Content-Type": "application/json"}
    ws_id = "your-workspace-id"

    async with httpx.AsyncClient() as client:
        # Create two issues first
        r1 = await client.post(f"{base}/workspaces/{ws_id}/issues/",
            json={"title": "Setup database"}, headers=headers)
        r2 = await client.post(f"{base}/workspaces/{ws_id}/issues/",
            json={"title": "Build API layer"}, headers=headers)
        issue1_id = r1.json()["id"]
        issue2_id = r2.json()["id"]

        # Issue 1 blocks Issue 2
        dep = await client.post(
            f"{base}/workspaces/{ws_id}/issues/{issue1_id}/dependencies/",
            json={"depends_on_issue_id": issue2_id, "type": "blocks"},
            headers=headers)
        print(dep.json())

        # List dependencies
        deps = await client.get(
            f"{base}/workspaces/{ws_id}/issues/{issue1_id}/dependencies/",
            headers=headers)
        print(deps.json())

asyncio.run(main())
Blocking Chain: Related Issues:

Best Practices

Choose the appropriate dependency type:
  • blocks: Use when one issue must be completed before another can start
  • related: Use for issues that share context but don’t block each other
  • duplicates: Use when multiple issues report the same problem
While the API doesn’t prevent circular dependencies, avoid creating chains where Issue A blocks Issue B, and Issue B blocks Issue A. This creates deadlock situations in project planning.
Dependencies appear when querying either issue in the relationship. Use this to discover related work when viewing any issue in your project.
Delete dependencies when issues are resolved to keep the dependency graph clean and relevant for active work.

Testing

Run the dependency service tests to verify functionality:
pytest tests/test_new_gaps.py::TestDependencyService -v
pytest tests/test_new_api_integration.py::TestDependencyRoutes -v

Issue Management

Core issue creation and management

Workspace API

Workspace-level operations and access