> ## Documentation Index > Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt > Use this file to discover all available pages before exploring further. # Prepare file uploads > Uses the shared Vault upload flow for up to 100 files. JSON body limit: 1 MiB. Provide targetUri or sessionId; @mc destinations also require scope. Vault checks destination access, creates missing folders, and applies onConflict (rename by default). PUT each file to its signed URL using the returned headers, then pass its uploadToken to completion. Initialization is not idempotent; do not retry blindly after a lost response. ## OpenAPI ````yaml /openapi.json post /files/uploads openapi: 3.0.3 info: title: Effective API version: 2.0.0 description: The public Effective REST API. Authenticate using an Effective API key. servers: - url: https://effectiveai.app/api/v2 description: Production security: - bearerAuth: [] paths: /files/uploads: post: tags: - Files summary: Prepare file uploads description: >- Uses the shared Vault upload flow for up to 100 files. JSON body limit: 1 MiB. Provide targetUri or sessionId; @mc destinations also require scope. Vault checks destination access, creates missing folders, and applies onConflict (rename by default). PUT each file to its signed URL using the returned headers, then pass its uploadToken to completion. Initialization is not idempotent; do not retry blindly after a lost response. operationId: initializeFileUploads requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2FileUploadCreate' responses: '200': description: Signed PUT instructions and any name conflicts. content: application/json: schema: $ref: '#/components/schemas/V2FileUploadCreateResponse' '400': description: Invalid request input. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '403': description: Write permission required. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '404': description: Upload destination or owner not found. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '409': description: Resource state conflicts with this request. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '413': description: Request exceeds 1 MiB. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '415': description: Content-Type must be application/json. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '500': description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' '503': description: Temporarily unavailable. Retry-After is in seconds. content: application/json: schema: $ref: '#/components/schemas/V2CodedError' security: - bearerAuth: [] components: schemas: V2FileUploadCreate: type: object properties: targetUri: type: string minLength: 1 description: >- Target folder URI; required unless sessionId is provided. artifact:// writes must use a vault root plus relative path (or a supported managed rater root), not an ordinary folder ID. @mc requires scope. sessionId: type: string description: >- Chat session ID. When provided, files are uploaded to the session folder (same location as chat composer base64 uploads). Mutually exclusive with targetUri. files: type: array items: type: object properties: path: type: string minLength: 1 description: >- Relative path from target folder (e.g., "file.pdf" or "subfolder/file.pdf") size: type: integer minimum: 0 description: File size in bytes mimeType: type: string description: MIME type (auto-detected from extension if omitted) metadata: type: object additionalProperties: nullable: true description: >- Optional metadata to attach to the artifact on creation. Merged into ArtifactBase.metadata. Use namespaced sub-keys (e.g. metadata.jsonui = {...}) to avoid collisions with other writers. Reserved top-level keys (e.g. _appScope, _prevVisibility) are managed by the server and will be overridden if present in the request. type: type: string minLength: 1 maxLength: 50 description: Artifact type to persist. Defaults to file. replaceTargetArtifactId: type: string format: uuid description: >- Existing artifact this uploaded file is intended to replace via /upload/replace. When provided, the server validates edit access to that target and marks the uploaded source as replacement-scoped. ownerId: type: string format: uuid description: >- Optional UUID of the owning record (e.g. form edition or product) ownerType: type: string description: Optional unconstrained owner kind (e.g. form_edition, product) required: - path - size minItems: 1 maxItems: 100 description: Files to upload (max 100 per request) onConflict: type: string enum: - fail - replace - rename default: rename description: 'How to handle name conflicts (default: rename)' scope: type: string pattern: ^mc:[A-Za-z0-9][A-Za-z0-9-]{0,127}$ description: >- Required only for @mc destinations. Overrides ambient Mission Control context. required: - files additionalProperties: false V2FileUploadCreateResponse: type: object properties: targetUri: type: string minLength: 1 description: Resolved target folder URI files: type: array items: type: object properties: path: type: string description: Actual path for upload (may differ from request if renamed) originalPath: type: string description: Original path from request (only present if renamed) signedUrl: type: string format: uri description: Pre-signed URL for direct PUT upload to storage headers: type: object additionalProperties: type: string description: Headers to include with PUT request (e.g., Content-Type) expiresAt: type: string description: URL expiration time (ISO 8601) uploadToken: type: string description: >- Opaque token containing upload metadata - pass back in complete request willReplace: type: boolean description: >- True if upload will replace an existing file (onConflict=replace) required: - path - signedUrl - expiresAt - uploadToken description: Upload details for files to upload conflicts: type: array items: type: object properties: path: type: string description: Relative path or URI of the conflicting item type: type: string enum: - file - folder description: Type of the existing item existingName: type: string description: Name of the existing item existingSize: type: integer description: Size of existing file (bytes) existingModifiedAt: type: string description: Last modified time (ISO 8601) existingItemCount: type: integer description: Number of items in existing folder required: - path - type - existingName description: Files not included due to conflict (when onConflict=fail) required: - targetUri - files V2CodedError: allOf: - $ref: '#/components/schemas/V2Error' - type: object properties: code: type: string minLength: 1 description: Stable error code. Clients must tolerate unknown future codes. details: type: array items: type: object properties: location: type: string enum: - path - query - header - body path: type: array items: type: string maxLength: 64 maxItems: 12 code: type: string enum: - required - invalid_type - invalid_value - unknown_field message: type: string minLength: 1 maxLength: 200 required: - location - path - code - message minItems: 1 maxItems: 20 description: Bounded safe validation issues; may omit some invalid fields. requestId: type: string minLength: 1 maxLength: 128 description: >- Existing server correlation for this HTTP attempt, when available. required: - code V2Error: type: object properties: error: type: string minLength: 1 description: Human-readable explanation of the failure. required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: 'Effective API key. Send Authorization: Bearer sk-eai-...' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.