> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Scheduled Task
> Create a scheduled task owned by the workspace API key
Creates a scheduled task owned by this workspace API key. New tasks start with `active` set to `true`. The response status is `201`. The body does not include `runCount`.
## Base URL
```
https://api.langdock.com/automations/v1
```
**Dedicated deployments**
Replace `api.langdock.com` with `/api/public` in all requests.
## Required scopes
This endpoint requires the `AUTOMATION_API` scope (**Scheduled Tasks API**) on a workspace API key.
A workspace can hold 10 tasks for this owner. The next create returns `400` with `AUTOMATION_LIMIT_REACHED`. An expired trial returns `403` with `TRIAL_EXPIRED`.
## Parameters
Send a JSON body. Unknown fields are rejected. Schedule rules are on the [Scheduled Tasks API Overview](/en/developer/scheduled-tasks-api/scheduled-tasks-overview).
| Parameter | Type | Required | Description |
| -------------------------- | -------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| `name` | string | Yes | 1 to 200 characters. |
| `prompt` | string | Yes | 1 to 120000 characters. |
| `frequency` | string | Yes | `MANUAL`, `DAILY`, `WEEKDAYS`, `WEEKLY`, `MONTHLY`, or `SELECTED_WEEKDAYS`. |
| `timeOfDay` | string | For every frequency except `MANUAL` | 24 hour `HH:mm`. |
| `dayOfWeek` | integer | For `WEEKLY` | 0 (Sunday) through 6 (Saturday). |
| `dayOfMonth` | integer | For `MONTHLY` | 1 through 31. |
| `daysOfWeek` | integer\[] | For `SELECTED_WEEKDAYS` | At least one day, each 0 through 6. At most 7 values. |
| `timezone` | string \| null | No | IANA name, at most 64 characters. Empty or omitted on a scheduled frequency is stored as `UTC`. |
| `modelMode` | string | No | `UNSET`, `EXPLICIT`, or `AUTO`. |
| `modelId` | string \| null | When `modelMode` is `EXPLICIT` | Model UUID. Must be in the same request. |
| `assistantId` | string \| null | No | Primary agent UUID. Must be available to the key. |
| `taggedAssistantId` | string \| null | No | Extra agent mention. Dropped when the key cannot use it. |
| `taggedIntegrationIds` | string\[] | No | At most 20. Inaccessible ids are dropped. |
| `taggedKnowledgeFolderIds` | string\[] | No | At most 20. Inaccessible ids are dropped. |
| `taggedWorkflowIds` | string\[] | No | At most 20. Inaccessible ids are dropped. |
| `taggedSkillSlugs` | string\[] | No | At most 20. Each slug is at most 100 characters. Inaccessible slugs are dropped. |
| `attachmentIds` | string\[] | No | At most 20 attachment UUIDs already owned by this key in the workspace. |
## Example
```javascript theme={null}
const axios = require("axios");
async function createScheduledTask() {
const response = await axios.post(
"https://api.langdock.com/automations/v1",
{
name: "Monday pipeline brief",
prompt: "Summarize overnight pipeline changes for the revenue team.",
frequency: "WEEKLY",
timeOfDay: "09:00",
dayOfWeek: 1,
timezone: "Europe/Berlin"
},
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
}
);
console.log(response.status, response.data.automation.id);
}
createScheduledTask();
```
## Response format
### Success response (201 Created)
`automation` matches the [scheduled task object](/en/developer/scheduled-tasks-api/scheduled-tasks-overview) without `runCount`.
```typescript theme={null}
{
automation: {
id: string;
createdAt: string;
name: string;
prompt: string;
modelId: string | null;
modelMode: "UNSET" | "EXPLICIT" | "AUTO";
assistantId: string | null;
taggedAssistantId: string | null;
frequency:
| "MANUAL"
| "DAILY"
| "WEEKDAYS"
| "WEEKLY"
| "MONTHLY"
| "SELECTED_WEEKDAYS";
timeOfDay: string | null;
dayOfWeek: number | null;
dayOfMonth: number | null;
daysOfWeek: number[];
timezone: string | null;
active: boolean;
lastRunAt: string | null;
attachments: Array<{
id: string;
name: string;
mimeType: string | null;
type: string | null;
}>;
taggedIntegrationIds: string[];
taggedKnowledgeFolderIds: string[];
taggedWorkflowIds: string[];
taggedSkillSlugs: string[];
};
}
```
## Error handling
| Status code | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Invalid body, or message `AUTOMATION_LIMIT_REACHED` |
| 401 | Invalid or missing API key, or the key user was not found |
| 403 | Missing `AUTOMATION_API`, a personal API key, Scheduled Tasks disabled, no product access, `TRIAL_EXPIRED`, or `AUTOMATION_TAG_ACCESS_DENIED` |
| 405 | Method not allowed |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
An invalid body returns `400` with message `Invalid request` and an `errors` array. Missing clock fields use `timeOfDay is required for scheduled automations`, `dayOfWeek is required for weekly automations`, `dayOfMonth is required for monthly automations`, or `daysOfWeek is required for selected weekday automations`. An invalid timezone uses `timezone must be a valid IANA identifier`. `modelMode` `EXPLICIT` without `modelId` uses `modelId is required for explicit model selection`. An expired trial returns `403` with code `TRIAL_EXPIRED` and message `Your trial has expired. Upgrade to continue.`
Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## OpenAPI
````yaml POST /automations/v1
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/automations/v1:
post:
tags:
- Scheduled Tasks
summary: Create a scheduled task
description: >-
Creates a scheduled task owned by this workspace API key. New tasks
start active. The response does not include runCount.
operationId: createScheduledTask
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- name
- prompt
- frequency
properties:
name:
type: string
minLength: 1
maxLength: 200
prompt:
type: string
minLength: 1
maxLength: 120000
frequency:
type: string
enum:
- MANUAL
- DAILY
- WEEKDAYS
- WEEKLY
- MONTHLY
- SELECTED_WEEKDAYS
timeOfDay:
type: string
nullable: true
description: 24 hour HH:mm. Required unless frequency is MANUAL.
dayOfWeek:
type: integer
minimum: 0
maximum: 6
nullable: true
description: Required for WEEKLY. 0 is Sunday and 6 is Saturday.
dayOfMonth:
type: integer
minimum: 1
maximum: 31
nullable: true
description: Required for MONTHLY.
daysOfWeek:
type: array
maxItems: 7
items:
type: integer
minimum: 0
maximum: 6
description: Required for SELECTED_WEEKDAYS.
timezone:
type: string
nullable: true
maxLength: 64
description: >-
IANA timezone. Empty or omitted on a scheduled frequency is
stored as UTC.
modelMode:
type: string
enum:
- UNSET
- EXPLICIT
- AUTO
modelId:
type: string
format: uuid
nullable: true
description: Required in the same request when modelMode is EXPLICIT.
assistantId:
type: string
format: uuid
nullable: true
taggedAssistantId:
type: string
format: uuid
nullable: true
taggedIntegrationIds:
type: array
maxItems: 20
items:
type: string
format: uuid
taggedKnowledgeFolderIds:
type: array
maxItems: 20
items:
type: string
format: uuid
taggedWorkflowIds:
type: array
maxItems: 20
items:
type: string
format: uuid
taggedSkillSlugs:
type: array
maxItems: 20
items:
type: string
maxLength: 100
attachmentIds:
type: array
maxItems: 20
items:
type: string
format: uuid
responses:
'201':
description: >-
Scheduled task created. The automation object does not include
runCount.
'400':
description: Invalid body, or message AUTOMATION_LIMIT_REACHED
'401':
description: Invalid or missing API key, or the key user was not found
'403':
description: >-
Missing AUTOMATION_API, a personal API key, Scheduled Tasks
disabled, no product access, TRIAL_EXPIRED, or
AUTOMATION_TAG_ACCESS_DENIED
'405':
description: Method not allowed
'429':
description: Rate limit exceeded
'500':
description: Internal server error
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````