> ## 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. # Add a file > Add an uploaded file to a project, account, contact, intake, or the Library: pass exactly one of projectId, accountId, contactId, intakeId, or library. Create the upload with POST /uploads and PUT the file's bytes to its url first. Parley then extracts the file's text in the background, and the file can be read once its status is ready. Adding the same upload again returns the same file; adding it anywhere else returns 409 UPLOAD_ALREADY_ADDED. ## OpenAPI ````yaml https://api.parley.so/openapi.json post /files 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: /files: post: tags: - Files summary: Add a file description: >- Add an uploaded file to a project, account, contact, intake, or the Library: pass exactly one of projectId, accountId, contactId, intakeId, or library. Create the upload with POST /uploads and PUT the file's bytes to its url first. Parley then extracts the file's text in the background, and the file can be read once its status is ready. Adding the same upload again returns the same file; adding it anywhere else returns 409 UPLOAD_ALREADY_ADDED. operationId: createFile requestBody: required: true content: application/json: schema: type: object properties: projectId: type: string minLength: 1 description: >- Add it to this project's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library. accountId: type: string minLength: 1 description: >- Add it to this account's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library. contactId: type: string minLength: 1 description: >- Add it to this contact's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library. intakeId: type: string minLength: 1 description: >- Add it to this intake's files. Pass exactly one of projectId, accountId, contactId, intakeId, or library. library: const: true description: >- true for the organization's Library. Pass exactly one of projectId, accountId, contactId, intakeId, or library. uploadId: type: string minLength: 1 description: >- The id of an upload, once its bytes have been PUT to its url, holding the file to add. It keeps its file name. Adding the same upload again returns the same file. folderId: type: string minLength: 1 description: Put it inside this folder. Omit for the top level. required: - uploadId additionalProperties: false responses: '201': description: Created. content: application/json: schema: $ref: '#/components/schemas/File' headers: Location: description: The URL of the created resource. schema: type: string '400': description: The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationFailedError' - $ref: '#/components/schemas/InvalidReferenceError' '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' '409': description: The request conflicts with the current state. UPLOAD_ALREADY_ADDED. content: application/json: schema: $ref: '#/components/schemas/UploadAlreadyAddedError' '429': description: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' components: schemas: File: description: A file or a folder, told apart by type. examples: - type: file id: cmf2y1a2b0003abcd name: engagement-letter.pdf location: type: project id: cmf2x8k0q0001abcd name: Acme Corp H-1B petition folder: type: folder id: cmf2y0z9x0004abcd name: Evidence mediaType: application/pdf status: ready createdAt: '2026-10-03T12:00:00.000Z' updatedAt: '2026-10-03T12:01:30.000Z' oneOf: - $ref: '#/components/schemas/FileItem' - $ref: '#/components/schemas/FolderItem' discriminator: propertyName: type mapping: file: '#/components/schemas/FileItem' folder: '#/components/schemas/FolderItem' 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 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 UploadAlreadyAddedError: type: object properties: error: type: object properties: code: type: string const: UPLOAD_ALREADY_ADDED message: type: string examples: - This upload was already added somewhere else. 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 FileItem: type: object properties: type: const: file id: type: string minLength: 1 description: The file or folder ID. name: type: string description: The name, including any file extension. location: anyOf: - $ref: '#/components/schemas/RecordRef' - type: object properties: type: const: intake id: type: string description: Its ID. name: type: string description: The intake title. required: - type - id - name description: The intake's type, ID, and name. - type: object properties: type: const: library required: - type description: The organization's shared Library. description: >- Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library. folder: anyOf: - type: object properties: type: const: folder id: type: string description: Its ID. name: type: string description: The folder name. required: - type - id - name description: The folder's type, ID, and name. - type: 'null' description: The folder it is in, or null at the top level. createdAt: type: string format: date-time description: When it was added. updatedAt: type: string format: date-time description: When it was last updated, including processing, renames, and moves. mediaType: anyOf: - type: string - type: 'null' description: >- The file's media type, such as application/pdf, from its extension, or null when the extension isn't recognized. status: enum: - pending - processing - ready - failed type: string description: >- Whether Parley has extracted the file's text: pending (queued), processing, ready (its text can be read), or failed (download it instead). required: - type - id - name - location - folder - createdAt - updatedAt - mediaType - status FolderItem: type: object properties: type: const: folder id: type: string minLength: 1 description: The file or folder ID. name: type: string description: The name, including any file extension. location: anyOf: - $ref: '#/components/schemas/RecordRef' - type: object properties: type: const: intake id: type: string description: Its ID. name: type: string description: The intake title. required: - type - id - name description: The intake's type, ID, and name. - type: object properties: type: const: library required: - type description: The organization's shared Library. description: >- Whose files these are: a project's, an account's, a contact's, or an intake's, or the organization's Library. folder: anyOf: - type: object properties: type: const: folder id: type: string description: Its ID. name: type: string description: The folder name. required: - type - id - name description: The folder's type, ID, and name. - type: 'null' description: The folder it is in, or null at the top level. createdAt: type: string format: date-time description: When it was added. updatedAt: type: string format: date-time description: When it was last updated, including processing, renames, and moves. required: - type - id - name - location - folder - createdAt - updatedAt RecordRef: type: object properties: type: enum: - project - account - contact type: string description: 'The kind of record: project, account, or contact.' id: type: string description: Its ID. name: type: string description: >- The record's name. A contact's is its first and last name, or an email address when it has no name. required: - type - id - name description: A reference to a project, account, or contact. 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.