> ## Documentation Index > Fetch the complete documentation index at: https://scorecard-d65b5e8a-docs-attachment-api-reference.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Initiate Attachment Upload > Initiates (or deduplicates) an upload of a file attached to a session. If the exact content is already stored for this (session ID, file path), the response has `alreadyExists: true` and no upload is needed. Otherwise, PUT the file bytes to the returned `uploadUrl`, then call the commit endpoint. Re-initiating an existing (session ID, file path) with new content updates the attachment in place on commit. ## OpenAPI ````yaml post /attachments openapi: 3.1.0 info: title: Scorecard API description: REST API for Scorecard version: 1.0.0 servers: - url: https://api2.scorecard.io/api/v2 security: - ApiKeyAuth: [] paths: /attachments: post: summary: Initiate Attachment Upload description: >- Initiates (or deduplicates) an upload of a file attached to a session. If the exact content is already stored for this (session ID, file path), the response has `alreadyExists: true` and no upload is needed. Otherwise, PUT the file bytes to the returned `uploadUrl`, then call the commit endpoint. Re-initiating an existing (session ID, file path) with new content updates the attachment in place on commit. operationId: initiateAttachment requestBody: content: application/json: schema: type: object properties: sessionId: type: string minLength: 1 maxLength: 256 description: >- The session ID the attachment belongs to. Matches the `session.id` emitted on OTel spans, which is how attachments are joined to traces and records. example: c59e5bd0-e5eb-4bf0-a08a-01f7e8f712c7 filePath: type: string minLength: 1 maxLength: 1024 description: >- The logical file path of the attachment (e.g. the path the agent wrote on disk). Together with the session ID it identifies the attachment: re-uploading the same path in the same session updates the existing attachment in place. example: /tmp/report.pdf sha256: type: string pattern: ^[0-9a-f]{64}$ description: Lowercase hex SHA-256 of the file content. example: >- 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 sizeBytes: type: integer minimum: 0 description: Size of the file in bytes. example: 482133 contentType: type: string minLength: 1 maxLength: 256 description: MIME type of the file. example: application/pdf filename: type: string minLength: 1 maxLength: 512 description: Display filename. Defaults to none. example: report.pdf metadata: type: object additionalProperties: true description: Arbitrary metadata to store with the attachment. x-stainless-any: true required: - sessionId - filePath - sha256 - sizeBytes - contentType examples: Initiate an upload: value: sessionId: c59e5bd0-e5eb-4bf0-a08a-01f7e8f712c7 filePath: /tmp/report.pdf sha256: >- 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 sizeBytes: 482133 contentType: application/pdf filename: report.pdf summary: Initiate an upload description: >- Declare a file produced during a session. The response tells you whether bytes need to be uploaded. responses: '201': description: >- Upload initiated (or content already stored). If `alreadyExists` is false, PUT the bytes to `uploadUrl` and then commit. content: application/json: schema: type: object properties: id: type: string format: uuid description: The ID of the Attachment. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 alreadyExists: type: boolean description: >- True if this exact content is already stored for this (session, file path) — no upload is needed and no upload URL is returned. uploadUrl: type: - string - 'null' description: >- Signed URL to PUT the file bytes to. Null when `alreadyExists` is true. uploadMethod: type: - string - 'null' enum: - PUT - null description: HTTP method to use with `uploadUrl`. expiresAt: type: - string - 'null' description: ISO 8601 expiry of `uploadUrl`. required: - id - alreadyExists - uploadUrl - uploadMethod - expiresAt examples: Upload needed: value: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 alreadyExists: false uploadUrl: >- https://storage.example.com/object/upload/sign/attachments/development/org_123/session/3fa85f64?token=abc uploadMethod: PUT expiresAt: '2026-07-13T12:00:00.000Z' summary: Upload needed description: >- The content is new; PUT the file to `uploadUrl`, then commit. Already stored: value: id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 alreadyExists: true uploadUrl: null uploadMethod: null expiresAt: null summary: Already stored description: >- This exact content is already attached to the session; nothing to upload. '401': $ref: '#/components/responses/UnauthenticatedError' '500': $ref: '#/components/responses/ServiceError' components: responses: UnauthenticatedError: description: Error indicating that the request is not authenticated. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: Authentication failure: value: code: UNAUTHORIZED message: Invalid or missing authentication token details: {} summary: Authentication failure description: >- Error returned when authentication credentials are invalid or missing. ServiceError: description: >- An internal service error indicating an issue with the Scorecard service. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: Internal error: value: code: INTERNAL_ERROR message: An unexpected error occurred while processing your request. details: {} summary: Internal error description: Generic error when an unexpected internal issue occurs. schemas: ApiError: type: object properties: code: type: string message: type: string details: type: object additionalProperties: true x-stainless-any: true required: - code - message - details description: An API error. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: starts with ak_ ````