Create Share Link

Create a shareable link for viewing task progress and results.

Endpoint

POST https://api.xmz.ai/v1/agentrix/tasks/:taskId/share

Authentication

Requires API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Important Notes

• Owner Only: Only the task owner can create share links
• Cloud Mode Only: Only supports tasks running in cloud mode (tasks with machineId must be null)
• Permissions: Control what viewers can do via permission flags

Path Parameters

Parameter	Type	Required	Description
taskId	string	Yes	Task identifier

Request Body

All fields are optional. If not provided, default permissions apply.

Parameter	Type	Default	Description
permissions	object	See below	Access permissions configuration

Permissions Object

Field	Type	Default	Description
canSendMessage	boolean	false	Allow sending messages to the task
canCreatePr	boolean	false	Allow creating pull requests
canApprovePr	boolean	false	Allow approving pull requests
canViewPr	boolean	true	Allow viewing pull requests
canMergePr	boolean	false	Allow merging pull requests

Request Body Schema

{
  "permissions": {
    "canSendMessage": false,
    "canCreatePr": false,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

Response

Success Response (201 Created)

{
  "shareCode": "abc123xyz"
}

Response Fields

Field	Type	Description
shareCode	string	Share code for accessing the task

Error Responses

400 Bad Request

{
  "code": "INVALID_REQUEST",
  "error": "validation_error",
  "message": "Invalid request parameters"
}

401 Unauthorized

{
  "code": "UNAUTHORIZED",
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "code": "FORBIDDEN",
  "error": "forbidden",
  "message": "Only task owner can create share links"
}

404 Not Found

{
  "code": "TASK_NOT_FOUND",
  "error": "not_found",
  "message": "Task not found"
}

Examples

Example 1: Default Permissions (View-Only)

Create a share link with default permissions (view-only):

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example 2: Custom Permissions

Create a share link that allows messaging and viewing PRs:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canCreatePr": false,
      "canApprovePr": false,
      "canViewPr": true,
      "canMergePr": false
    }
  }'

Example 3: Full Permissions

Create a share link with all permissions enabled:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canCreatePr": true,
      "canApprovePr": true,
      "canViewPr": true,
      "canMergePr": true
    }
  }'

Usage Flow

1. Task Owner: Calls this endpoint to create a share link
2. Receive Share Code: API returns a shareCode (e.g., abc123xyz)
3. Share with Others: Owner shares the code with viewers
4. Viewer Authentication: Viewers authenticate using GET /v1/auth/share?code=<shareCode>
5. Access Task: Viewers can access the task according to their permissions

Permission Details

View-Only Access

Default permissions allow viewing task progress and results only:

{
  "permissions": {
    "canSendMessage": false,
    "canCreatePr": false,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

Interactive Access

Allow viewers to send messages and interact with the task:

{
  "permissions": {
    "canSendMessage": true,
    "canCreatePr": true,
    "canApprovePr": false,
    "canViewPr": true,
    "canMergePr": false
  }
}

Full Access

Give viewers full control (use with caution):

{
  "permissions": {
    "canSendMessage": true,
    "canCreatePr": true,
    "canApprovePr": true,
    "canViewPr": true,
    "canMergePr": true
  }
}

Security Best Practices

1. Minimal Permissions: Grant only the permissions viewers need
2. View-Only by Default: Most use cases only need canViewPr: true
3. Careful with Write Access: Be cautious with canMergePr and canApprovePr
4. Share Privately: Share codes only with intended viewers
5. Monitor Access: Track who is accessing your shared tasks

Common Use Cases

Demo or Portfolio

Share a completed task to showcase your work (view-only):

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Collaborative Review

Allow team members to view and comment on a task:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canSendMessage": true,
      "canViewPr": true
    }
  }'

Client Presentation

Share with clients who need to approve PRs:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/task-xxx/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "canViewPr": true,
      "canApprovePr": true
    }
  }'

Limitations

• Cloud Mode Only: Local machine tasks cannot be shared
• Task Owner Only: Only the user who created the task can create share links
• No Expiration: Share codes currently do not expire (manage access carefully)

Related Endpoints

• Create Task - Create a task to share
• Get Share Info - Retrieve share link details (GET /v1/tasks/:taskId/share)
• Authenticate with Share Code - Viewer authentication (GET /v1/auth/share?code=<shareCode>)

Need Help?

• View API Overview for general API information
• Learn about Create Task to create shareable tasks
• Report issues on GitHub