> ## Documentation Index > Fetch the complete documentation index at: https://docs.parley.so/llms.txt > Use this file to discover all available pages before exploring further. # Create an automation > Create an automation: instructions Parley's assistant carries out whenever one of its triggers fires, as you, with nobody present. The automation is active as soon as it's created. Without a trigger it only runs when someone starts a run with POST /automations/{id}/runs. ## OpenAPI ````yaml https://api.parley.so/openapi.json post /automations openapi: 3.1.1 info: title: Parley API version: 1.0.0 description: >- Manage Parley's projects (matters or cases), accounts (client organizations), contacts (people), tasks, custom fields, notes, files, activity, automations, and skills. Records refer to each other as { type, id, name } references; writes take IDs. Errors are { error: { code, message, details } }, where code names what went wrong and each operation lists the codes it can return. In a query string, write a timestamp's offset as Z or %2B, because a raw + arrives as a space. The MCP server at /mcp offers the same data as a smaller set of tools. servers: - url: https://api.parley.so/v1 security: - bearerAuth: [] tags: - name: Projects description: >- A project is a matter or case: it groups the files, notes, activity, and tasks for one engagement, and links to the accounts and contacts it involves. - name: Accounts description: >- An account is a client organization. Contacts belong to it, and projects link to it. - name: Contacts description: >- A contact is a person, optionally belonging to one account and linked to projects. - name: Tasks description: >- A task is a to-do with a status, assignee, and due date, optionally about one project, account, or contact. - name: Fields description: >- Custom fields defined for projects, accounts, contacts, or tasks. Records carry their values in fields, keyed by field name. - name: Notes description: >- Markdown notes on a project, account, or contact. Updates take the version you last read, so concurrent edits fail with 409 VERSION_CONFLICT instead of overwriting. - name: Files description: >- Files and folders of a project, account, contact, or intake, or the organization's Library. Add a file by creating an upload, PUTting its bytes, and adding the upload to a location. - name: Activity description: >- What happened across the organization or on one record: changes, links, notes, files, USCIS case updates, and synced emails and meetings. Each item's kind says which details it carries. - name: Sessions description: >- Conversations with Parley's assistant, from the web app, Word, Outlook, automation runs, and the API. Start one with a message, follow up or steer it while it works, and read its replies. - name: Automations description: >- Instructions Parley's assistant carries out on a schedule, as the person who created them, with nobody present. - name: Skills description: >- Reusable playbooks for Parley's assistant: a SKILL.md plus optional bundled documents, addressed by slug. - name: Users description: The people in your organization, and the caller. paths: /automations: post: tags: - Automations summary: Create an automation description: >- Create an automation: instructions Parley's assistant carries out whenever one of its triggers fires, as you, with nobody present. The automation is active as soon as it's created. Without a trigger it only runs when someone starts a run with POST /automations/{id}/runs. operationId: createAutomation requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 120 description: The automation name. description: type: string maxLength: 2000 description: A short summary of what the automation does. instructions: type: string minLength: 1 maxLength: 20000 description: >- The prompt Parley's assistant carries out on every run, up to 20,000 characters. Nobody is there to answer questions during a run, so say what to check, what counts as worth reporting, and what the report should look like. triggers: type: array maxItems: 10 items: anyOf: - type: object properties: type: const: cron cron: type: string minLength: 1 maxLength: 100 description: >- A five-field cron expression (minute, hour, day of month, month, day of week), such as 0 9 * * 1-5 for 9:00 AM on weekdays or 30 16 * * 5 for 4:30 PM on Fridays. A trigger can fire at most once an hour, and macros such as @daily and a seconds field aren't supported. timezone: type: string minLength: 1 description: >- The IANA time zone the cron expression is read in, such as America/New_York. Defaults to your time zone in Parley. required: - type - cron additionalProperties: false - type: object properties: type: const: event event: enum: - project.created - account.created - contact.created type: string description: >- What happens in Parley to start a run: someone creates a project, an account, or a contact. Records that email and calendar sync create don't count. required: - type - event additionalProperties: false description: >- A trigger to add, such as { "type": "cron", "cron": "0 9 * * 1-5" } for 9:00 AM on weekdays, or { "type": "event", "event": "project.created" } for each new project. description: >- What starts the automation on its own, such as [{ "type": "cron", "cron": "0 9 * * 1-5" }] for 9:00 AM on weekdays. At most 10. Leave it out for an automation that only runs when someone starts a run. projectId: type: string minLength: 1 description: >- A project to run the automation in, which needs edit access to it. Leave it out for an automation that runs across the organization. required: - name - instructions additionalProperties: false responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/Automation' headers: Location: description: The URL of the created resource. schema: type: string '400': description: >- The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE, INVALID_TRIGGER. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationFailedError' - $ref: '#/components/schemas/InvalidReferenceError' - $ref: '#/components/schemas/InvalidTriggerError' '401': description: Missing or invalid credentials. UNAUTHORIZED. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: You don't have permission. FORBIDDEN. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '429': description: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' components: schemas: Automation: type: object properties: id: type: string minLength: 1 description: The automation ID. name: type: string description: The automation name. description: anyOf: - type: string - type: 'null' description: A short summary of what the automation does, or null. status: enum: - active - paused type: string description: >- active: the automation runs when its triggers fire. paused: its triggers are on hold, and the automation only runs when someone starts a run. nextRunAt: anyOf: - type: string format: date-time - type: 'null' description: >- When a trigger next starts a run, or null for an automation that is paused or has no scheduled trigger. project: anyOf: - $ref: '#/components/schemas/ProjectRef' - type: 'null' description: >- The project the automation runs in, with that project's files, notes, and linked records as its context, or null for an automation that runs across the organization. lastRun: anyOf: - type: object properties: id: type: string minLength: 1 description: The run ID. status: enum: - pending - running - succeeded - failed - canceled - timed_out type: string description: >- pending: queued and not yet started. running: in progress. succeeded, failed, canceled, and timed_out are final. startedAt: anyOf: - type: string format: date-time - type: 'null' description: When the run started. endedAt: anyOf: - type: string format: date-time - type: 'null' description: When the run finished. required: - id - status - startedAt - endedAt - type: 'null' description: The most recent run, or null for an automation that has never run. createdAt: type: string format: date-time description: When the automation was created. updatedAt: type: string format: date-time description: When the automation or its triggers were last changed. triggers: type: array items: $ref: '#/components/schemas/AutomationTrigger' description: >- What starts the automation on its own, oldest first. Empty for an automation that only runs when someone starts a run. instructions: type: string description: >- The automation's instructions: the prompt Parley's assistant carries out on every run. required: - id - name - description - status - nextRunAt - project - lastRun - createdAt - updatedAt - triggers - instructions ValidationFailedError: type: object properties: error: type: object properties: code: type: string const: VALIDATION_FAILED message: type: string examples: - The request is invalid. details: type: object properties: issues: type: array items: type: object properties: path: type: string description: >- Where the problem is, as a dotted path into the input such as accountIds.add.0 or reminder.remindAt. Empty for the input as a whole. message: type: string description: What is wrong with the value. required: - path - message description: Each problem with the input. required: - issues required: - code - message - details required: - error InvalidReferenceError: type: object properties: error: type: object properties: code: type: string const: INVALID_REFERENCE message: type: string examples: - >- The request refers to a record or user that doesn't exist or that you can't use. details: type: object properties: field: type: string description: The input that holds the reference, such as accountIds. ids: type: array items: type: string description: The IDs that could not be used. required: - field - ids required: - code - message - details required: - error InvalidTriggerError: type: object properties: error: type: object properties: code: type: string const: INVALID_TRIGGER message: type: string examples: - A trigger is not valid. required: - code - message required: - error UnauthorizedError: type: object properties: error: type: object properties: code: type: string const: UNAUTHORIZED message: type: string examples: - Missing or invalid credentials. required: - code - message required: - error ForbiddenError: type: object properties: error: type: object properties: code: type: string const: FORBIDDEN message: type: string examples: - You don't have permission to do this. required: - code - message required: - error TooManyRequestsError: type: object properties: error: type: object properties: code: type: string const: TOO_MANY_REQUESTS message: type: string examples: - Too many requests. required: - code - message required: - error ProjectRef: type: object properties: type: const: project id: type: string description: Its ID. name: type: string description: The project name. required: - type - id - name description: The project's type, ID, and name. AutomationTrigger: description: >- Something that starts a run. cron: a schedule. event: something that happens in Parley. More types will be added, so skip any type you do not recognize. oneOf: - $ref: '#/components/schemas/CronTrigger' - $ref: '#/components/schemas/EventTrigger' discriminator: propertyName: type mapping: cron: '#/components/schemas/CronTrigger' event: '#/components/schemas/EventTrigger' CronTrigger: type: object properties: id: type: string minLength: 1 description: The trigger ID. type: const: cron cron: type: string description: >- A five-field cron expression (minute, hour, day of month, month, day of week), such as 0 9 * * 1-5 for 9:00 AM on weekdays or 30 16 * * 5 for 4:30 PM on Fridays. timezone: type: string description: >- The IANA time zone the cron expression is read in, such as America/New_York. required: - id - type - cron - timezone EventTrigger: type: object properties: id: type: string minLength: 1 description: The trigger ID. type: const: event event: enum: - project.created - account.created - contact.created type: string description: >- What happens in Parley to start a run: someone creates a project, an account, or a contact. Records that email and calendar sync create don't count. required: - id - type - event securitySchemes: bearerAuth: type: http scheme: bearer description: A Parley API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.