Agent Schedule API

The Agent Schedule API lets agent services read user schedules, create scheduled tasks, and run scheduling calculations such as business-day counts and task end times.

Authentication

Every request requires both an organizationId and an organizationApiKey. Send them as headers:

X-Organization-Id: <your-organization-id>
X-Organization-Api-Key: <your-agent-api-key>

or as explicit query parameters (GET) or body fields (POST).

• Users must belong to the organisation to be included in queries or task assignments.
• 403 Forbidden is returned if users don’t belong to the organisation.
• 404 Not Found is returned if users don’t exist.

Timezone

Scheduling uses the organisation timezone from its settings, defaulting to Australia/Sydney when not configured.

Get user schedules

Retrieve tasks and schedules for specified users within a date range.

GET /api/agents/schedules

Query parameters

Parameter	Type	Required	Description
organizationId	string	Yes	Organisation to filter tasks by.
organizationApiKey	string	Yes	Signed API key from the agent payload.
userIds	string	Yes	Comma-separated list of user IDs.
startDate	string	Yes	Start date in ISO 8601 format (e.g. 2025-10-01).
endDate	string	Yes	End date in ISO 8601 format (e.g. 2025-10-31).

Example request

curl -X GET "https://api.runnit.io/api/agents/schedules?organizationId=<your-organization-id>&userIds=user-uuid-1,user-uuid-2&startDate=2025-10-01&endDate=2025-10-31" \
  -H "X-Organization-Id: <your-organization-id>" \
  -H "X-Organization-Api-Key: <your-agent-api-key>"

Response

{
  "organizationId": "org-uuid",
  "startDate": "2025-10-01T00:00:00.000Z",
  "endDate": "2025-10-31T23:59:59.999Z",
  "userSchedules": [
    {
      "userId": "user-uuid-1",
      "userDisplayName": "John Doe",
      "userEmail": "john@example.com",
      "calendarEntries": [
        {
          "id": "schedule-entry-uuid-1",
          "taskId": "task-uuid-1",
          "taskName": "Design Homepage Mockup",
          "taskDescription": "Create high-fidelity mockups for the homepage",
          "taskNumber": "TASK-001",
          "status": "in_progress",
          "priority": "high",
          "segmentIndex": 0,
          "totalSegments": 3,
          "isOverdue": false,
          "daysOverdue": 0,
          "startTime": "2025-10-01T09:00:00.000Z",
          "endTime": "2025-10-01T17:30:00.000Z",
          "durationMinutes": 450,
          "estimatedHours": 7.5,
          "projectId": "project-uuid-1",
          "projectName": "Website Redesign",
          "projectJobNumber": "JOB-2025-001",
          "clientName": "Acme Corp",
          "assignedToId": "user-uuid-1",
          "tags": ["design", "ui/ux"]
        }
      ]
    }
  ]
}

Calendar entry fields

Field	Type	Description
id	string	Unique schedule entry identifier.
taskId	string	Parent task identifier.
taskName	string	Name of the task.
taskDescription	string	Detailed description (optional).
taskNumber	string	Task number (e.g. TASK-001).
status	string	pending, scheduled, in_progress, completed, or cancelled.
priority	string	low, medium, high, or critical.
segmentIndex	number	Zero-based index of this segment for the task.
totalSegments	number	Total segments scheduled for the task.
isOverdue	boolean	Whether this segment starts after the brief due date.
daysOverdue	number	Days past due (0 if on time).
startTime	string	Segment start time (ISO 8601).
endTime	string	Segment end time (ISO 8601).
durationMinutes	number	Duration between start and end time, in minutes.
estimatedHours	number	Estimated hours for the task (optional).
projectId	string	Associated project ID.
projectName	string	Name of the project.
projectJobNumber	string	Project job number.
clientName	string	Client name, if available.
assignedToId	string	User this task is assigned to.
tags	string[]	Tags (optional).

The endpoint returns tasks that have both a planned start and end date, are not cancelled, overlap the requested date range, belong to the organisation, and are assigned to one of the requested users. Entries are grouped by user and sorted chronologically.

Create a task

Create a new scheduled task for a user.

POST /api/agents/tasks

Request body

Field	Type	Required	Description
organizationId	string	Yes	Organisation for security validation.
organizationApiKey	string	Yes	Signed API key from the agent payload.
projectId	string	Yes	The project UUID (an existing project, not a brief job UUID).
name	string	Yes	Task name.
status	string	Yes	pending, scheduled, in_progress, completed, or cancelled.
priority	string	Yes	low, medium, high, or critical.
assignedToId	string	Yes	User this task is assigned to.
plannedStartDate	string	Yes	ISO 8601 datetime when the task should start.
plannedEndDate	string	Yes	ISO 8601 datetime when the task should end.
description	string	No	Task description.
estimatedHours	number	No	Estimated hours to complete the task.
tags	string[]	No	Tags.
metadata	object	No	Additional metadata (see below).

Tasks cannot be scheduled in the past: plannedStartDate must be at or after the current time.

Scheduling metadata

When a task is scheduled past the project deadline, include these metadata fields:

{
  "briefJobId": "job-uuid-from-brief",
  "scheduledPastDueDate": true,
  "daysOverdue": 3,
  "originalTaskId": "temp-task-2",
  "schedulingNotes": "User's calendar was fully booked through the deadline"
}

Example request

curl -X POST https://api.runnit.io/api/agents/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "<your-organization-id>",
    "organizationApiKey": "<your-agent-api-key>",
    "projectId": "project-uuid",
    "name": "Design homepage mockups",
    "description": "Create high-fidelity mockups for the homepage",
    "status": "scheduled",
    "priority": "high",
    "assignedToId": "user-uuid-1",
    "estimatedHours": 16,
    "plannedStartDate": "2025-10-15T09:00:00.000Z",
    "plannedEndDate": "2025-10-17T16:30:00.000Z",
    "tags": ["design", "mockups"]
  }'

Response

{
  "success": true,
  "task": {
    "id": "created-task-uuid",
    "projectId": "project-uuid",
    "taskNumber": "TASK-123",
    "name": "Design homepage mockups",
    "status": "scheduled",
    "priority": "high",
    "assignedToId": "user-uuid-1",
    "estimatedHours": 16,
    "plannedStartDate": "2025-10-15T09:00:00.000Z",
    "plannedEndDate": "2025-10-17T16:30:00.000Z",
    "tags": ["design", "mockups"],
    "createdAt": "2025-10-12T10:30:00.000Z",
    "updatedAt": "2025-10-12T10:30:00.000Z"
  }
}

Error responses

// 400 Bad Request: missing field
{ "success": false, "error": "assignedToId is required", "statusCode": 400 }

// 400 Bad Request: scheduled in the past
{ "error": "Cannot schedule tasks in the past." }

// 403 Forbidden: user not in organisation
{ "error": "User user-uuid-1 does not belong to organization org-uuid" }

// 404 Not Found
{ "success": false, "error": "User not found: user-uuid-1", "statusCode": 404 }

Calculate business days

Calculate the number of business days (excluding weekends) between two dates.

GET /api/agents/calculate-business-days

Query parameters

Parameter	Type	Required	Description
organizationId	string	Yes	Organisation for security validation.
organizationApiKey	string	Yes	Signed API key from the agent payload.
startDate	string	Yes	Start date (ISO 8601).
endDate	string	Yes	End date (ISO 8601).

Response

{
  "success": true,
  "startDate": "2025-11-15T00:00:00.000Z",
  "endDate": "2025-11-18T00:00:00.000Z",
  "businessDays": 2,
  "calendarDays": 3
}

Calculate task schedule

Calculate when a task should end based on estimated hours, accounting for weekends and working hours per day.

POST /api/agents/calculate-task-schedule

Request body

Field	Type	Required	Description
organizationId	string	Yes	Organisation for security validation.
organizationApiKey	string	Yes	Signed API key from the agent payload.
estimatedHours	number	Yes	Estimated hours for the task.
startDateTime	string	Yes	Start date/time (ISO 8601).
hoursPerDay	number	No	Working hours per day. Defaults to 7.5.

Response

{
  "success": true,
  "startTime": "2025-10-15T09:00:00.000Z",
  "endTime": "2025-10-17T16:30:00.000Z",
  "durationMinutes": 960,
  "businessDays": 3,
  "input": {
    "estimatedHours": 16,
    "startDateTime": "2025-10-15T09:00:00.000Z",
    "hoursPerDay": 7.5
  }
}

Use the returned startTime and endTime as plannedStartDate and plannedEndDate when creating a task.