> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a file > Records a file you uploaded with an upload URL, as a knowledge base file or as a file attached to records, tasks or other resources. This is the last of three steps; see the steps above. **Knowledge base files.** With `isKbFile: true` the file is linked to your workspace automatically, and Heliyos copies it into the workers' workspace and extracts its text so workers can read it. Text extraction can finish a little after this call returns. **Retries are safe.** Creating a file again with the same `storageKey` returns the file already created, unchanged, instead of a second one. The file is checked before anything is written: `storageKey` must be inside your workspace's folder and `url` must point at exactly that key. Every entry in `relationships` must name a resource of your workspace. **1. Get an upload URL** Call **Create an upload URL** with the file's name, content type and size. **2. Upload the bytes** `PUT` the file to `presignedUrl` with the same `Content-Type` and `Content-Length`, without your API key. **3. Create the file** Call this endpoint with `storageKey` set to `fileKey`, `url` set to `https://{bucketName}.s3.amazonaws.com/{fileKey}`, `storageProvider` set to `S3`, and the same `fileName`, `mimeType` and `fileSize`. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_files_upload`](https://docs.heliyos.ai/mcp/tools/knowledge-base-and-files#heliyos-files-upload). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/platform/attachments openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/attachments: post: tags: - Files summary: Create a file description: >- Records a file you uploaded with an upload URL, as a knowledge base file or as a file attached to records, tasks or other resources. This is the last of three steps; see the steps above. **Knowledge base files.** With `isKbFile: true` the file is linked to your workspace automatically, and Heliyos copies it into the workers' workspace and extracts its text so workers can read it. Text extraction can finish a little after this call returns. **Retries are safe.** Creating a file again with the same `storageKey` returns the file already created, unchanged, instead of a second one. The file is checked before anything is written: `storageKey` must be inside your workspace's folder and `url` must point at exactly that key. Every entry in `relationships` must name a resource of your workspace. operationId: createAttachment parameters: [] requestBody: required: true content: application/json: schema: type: object properties: relationships: type: array items: type: object required: - objectId - objectType properties: objectId: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the resource to attach the file to. schemaId: type: string nullable: true description: >- The record's object (base schema) id. Send it for records; omit it or send null otherwise. objectType: type: string description: >- What `objectId` points at, for example `company`, `task` or `interaction`. example: company description: >- Optional. The resources to attach the file to: records (`company`, `people`, `deal` or a custom object's type, with `schemaId`), `task`, `note`, `comment`, `interaction`, `meeting`, `email`, `chat` or `list`, up to 200 entries. Each must belong to your workspace. An `organization` entry may only name your own workspace. fileName: type: string description: >- The name shown for the file. Usually the same name you sent for the upload URL. example: pricing-2026.pdf fileSize: type: integer minimum: 0 maximum: 26214400 description: >- The file's size in bytes, 0 to 26,214,400 (25 MB). Send the size you uploaded. example: 482113 mimeType: type: string description: >- The file's content type. Send the `mimeType` you uploaded with. example: application/pdf url: type: string maxLength: 2048 description: >- `https://{bucketName}.s3.amazonaws.com/{fileKey}`, built from the upload URL response. HTTPS only, with no port, credentials, query or fragment. Up to 2,048 characters. example: >- https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf storageProvider: type: string description: The storage provider. Send `S3`. example: S3 storageKey: type: string description: >- The `fileKey` from the upload URL response. A key outside your workspace's folder is refused. example: >- 66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf isKbFile: type: boolean description: >- `true` to add the file to the knowledge base, where workers read it. Defaults to `false`, a file attached to the resources in `relationships`. example: false description: type: string description: Optional. A short description of the file. May be empty. example: 2026 list prices and discount bands. required: - fileName - fileSize - mimeType - url - storageProvider - storageKey additionalProperties: false examples: recordFile: summary: A file attached to a company value: fileName: pricing-2026.pdf fileSize: 482113 mimeType: application/pdf url: >- https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf storageProvider: S3 storageKey: >- 66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf relationships: - objectId: 66f1a8c3e4b0a1b2c3d4e5f6 schemaId: 66a0f1e2d3c4b5a697880001 objectType: company knowledgeBase: summary: A knowledge base file value: fileName: sales-playbook.pdf fileSize: 1048576 mimeType: application/pdf url: >- https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf storageProvider: S3 storageKey: 66a0f1e2d3c4b5a697887766/1762248700000-sales-playbook.pdf isKbFile: true description: How we qualify and price enterprise deals. responses: '200': description: >- The created file, or the file already created with this `storageKey`. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. data: $ref: '#/components/schemas/File' example: meta: message: Attachment created successfully. data: _id: 6729c0d4e5f6a7b8c9d0e1f2 organizationId: 66a0f1e2d3c4b5a697887766 fileName: pricing-2026.pdf fileSize: 482113 mimeType: application/pdf url: >- https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf storageProvider: S3 storageKey: >- 66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf isKbFile: false relationships: - objectId: 66f1a8c3e4b0a1b2c3d4e5f6 schemaId: 66a0f1e2d3c4b5a697880001 objectType: company metadata: created: at: '2026-11-04T09:30:00.000Z' by: 66a0f1e2d3c4b5a697881111 updated: at: '2026-11-04T09:30:00.000Z' by: 66a0f1e2d3c4b5a697881111 '400': description: >- VALIDATION_FAILED: a field is missing or invalid, `fileSize` is above 25 MB, or `url` is not the storage URL of `storageKey`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: 'FORBIDDEN_ACTION: `storageKey` is outside your workspace''s folder.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- NOT_FOUND: a `relationships` entry names a resource that is not in your workspace. Nothing is written. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 File: type: object properties: _id: $ref: '#/components/schemas/ObjectId' id: allOf: - $ref: '#/components/schemas/ObjectId' description: The same value as `_id`. Present in list results only. organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the file belongs to. fileName: type: string description: The file's display name, as sent when the file was created. fileSize: type: integer description: Size in bytes, as sent when the file was created. mimeType: type: string description: The content type, for example `application/pdf`. url: type: string description: >- Where the file is stored. To download the file, use Get a file download link. storageProvider: type: string description: The storage provider recorded when the file was created. storageKey: type: string description: The file's storage key, inside your workspace's folder. description: type: string description: An optional description. Absent when none was sent. isKbFile: type: boolean description: >- `true` for a knowledge base file (workers read it), `false` for a file attached to a resource. relationships: type: array description: The resources the file is attached to. Not hydrated. items: $ref: '#/components/schemas/FileLink' metadata: $ref: '#/components/schemas/AuditMetadata' ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} FileLink: type: object description: A resource the file is attached to. properties: objectId: allOf: - $ref: '#/components/schemas/ObjectId' description: >- Id of the linked record, task, interaction, or of the workspace itself for a knowledge base file. schemaId: allOf: - $ref: '#/components/schemas/ObjectId' description: >- The linked record's object (base schema). Absent for links that are not records. objectType: type: string description: >- What the link points at: `company`, `people`, `deal` or a custom object's type for a record, `task`, `note`, `comment`, `interaction`, or `organization` for a knowledge base file. example: company AuditMetadata: type: object description: Who created and last changed the resource, and when. properties: created: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user (or the API key's owner) who created it. updated: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user who last changed it. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key, sent as `Authorization: Bearer heliyos_...`. Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.