Toolshed API Reference

// Request
{
  "name": "github.create-issue",
  "description": "Create a GitHub issue in a repository",
  "version": "1.0.0",
  "parameters": {
    "repo": { "type": "string", "required": true, "description": "Repository (owner/name)" },
    "title": { "type": "string", "required": true, "description": "Issue title" },
    "body": { "type": "string", "description": "Issue body (markdown)" },
    "labels": { "type": "array", "items": "string", "description": "Labels to apply" }
  },
  "integration": "github",
  "requiredScopes": ["repo"]
}
 
// Response 201
{
  "id": "tool_abc123",
  "name": "github.create-issue",
  "version": "1.0.0",
  "status": "active",
  "createdAt": "2025-03-01T10:00:00Z"
}

GET /tools?integration=github&q=issue

// Response 200
{
  "tools": [
    {
      "id": "tool_abc123",
      "name": "github.create-issue",
      "description": "Create a GitHub issue in a repository",
      "version": "1.0.0",
      "integration": "github"
    }
  ],
  "total": 1
}

// Request
{
  "query": "I need to create a GitHub issue",
  "limit": 5
}
 
// Response 200
{
  "results": [
    {
      "tool": { "id": "tool_abc123", "name": "github.create-issue" },
      "relevance": 0.95
    }
  ]
}

// Request
{
  "parameters": {
    "repo": "shellapps/experience",
    "title": "Bug: page not loading",
    "body": "Steps to reproduce..."
  },
  "context": {
    "agentId": "agent_xyz",
    "taskId": "task_123"
  }
}
 
// Response 200
{
  "executionId": "exec_abc",
  "status": "completed",
  "result": {
    "issueNumber": 42,
    "url": "https://github.com/shellapps/experience/issues/42"
  },
  "durationMs": 1200
}

// Request
{
  "redirectUri": "https://your-app.com/callback"
}
 
// Response 200
{
  "authorizationUrl": "https://github.com/login/oauth/authorize?client_id=..."
}

{
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'github.create-issue' not found",
    "status": 404
  }
}