Tutorials

This page gives practical end-to-end examples for humans, scripts, and agents. Use it when you want to move quickly without reverse-engineering the whole API.

1. Log in and inspect your workspaces

curl -X POST https://your-sally-domain.com/api/auth/login \
  -H 'Content-Type: application/json' \
  --data '{
    "email": "alex@example.com",
    "password": "StrongPassw0rd!"
  }'

curl https://your-sally-domain.com/api/auth/me \
  -H 'Authorization: Bearer YOUR_SESSION_TOKEN'

2. List projects in a workspace

curl https://your-sally-domain.com/api/projects \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Slug: sally'

3. Create a project

curl -X POST https://your-sally-domain.com/api/projects \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Slug: sally' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Website relaunch",
    "description": "Q2 launch work"
  }'

Sally creates a unique slug and the default project statuses automatically: Backlog, In Progress, Review, and Done.

4. Create a task with labels and a checklist

curl -X POST https://your-sally-domain.com/api/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Slug: sally' \
  -H 'Content-Type: application/json' \
  --data '{
    "projectId": "YOUR_PROJECT_ID",
    "title": "Ship onboarding flow",
    "description": "Finalize the operator onboarding flow.",
    "priority": "P2",
    "status": "In Progress",
    "labels": ["frontend", "priority"],
    "todos": [
      { "text": "QA pass" },
      { "text": "Polish copy" },
      { "text": "Deploy" }
    ]
  }'

5. Move a task to Review

curl -X POST https://your-sally-domain.com/api/tasks/YOUR_TASK_ID/move \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Slug: sally' \
  -H 'Content-Type: application/json' \
  --data '{ "targetStatus": "Review" }'

6. Invite a workspace member

curl -X POST https://your-sally-domain.com/api/auth/invite \
  -H 'Authorization: Bearer YOUR_SESSION_TOKEN_OR_API_KEY' \
  -H 'X-Workspace-Slug: sally' \
  -H 'Content-Type: application/json' \
  --data '{
    "email": "newuser@example.com",
    "role": "MEMBER"
  }'

7. Create a hosted MCP key

curl -X POST https://your-sally-domain.com/api/auth/mcp-keys \
  -H 'Authorization: Bearer YOUR_SESSION_TOKEN_OR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "label": "Claude hosted MCP",
    "workspaceId": "OPTIONAL_WORKSPACE_ID"
  }'

8. Call hosted MCP manually

curl -X POST https://your-sally-domain.com/mcp \
  -H 'Authorization: Bearer YOUR_SALLY_MCP_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"manual-test","version":"1.0.0"}
    }
  }'

9. Create a task through hosted MCP

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "task.create",
    "arguments": {
      "workspaceSlug": "sally",
      "projectId": "YOUR_PROJECT_ID",
      "title": "Validate hosted MCP flow",
      "description": "Confirm create/update/move behavior from MCP.",
      "status": "Backlog",
      "todos": [
        { "text": "Initialize session" },
        { "text": "Create task" },
        { "text": "Move to Review" }
      ]
    }
  }
}

10. Get a timesheet report

curl 'https://your-sally-domain.com/api/timesheets/report?from=2026-03-01&to=2026-03-31' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Workspace-Slug: sally'

Recommended workflows for agents

Safe read-first workflow

1. list workspaces
2. select one workspace
3. list projects
4. get project details
5. get or search tasks
6. only then mutate state

Safe write workflow

1. verify the exact workspace and project
2. fetch current statuses first
3. create or update the task with explicit statusId when possible
4. add comments describing what the automation changed
5. avoid assuming names are unique when ids are already known