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.

POST /attachments

Initiate Attachment Upload

JavaScript

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sessionId: 'c59e5bd0-e5eb-4bf0-a08a-01f7e8f712c7',
    filePath: '/tmp/report.pdf',
    sha256: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08',
    sizeBytes: 482133,
    contentType: 'application/pdf',
    filename: 'report.pdf'
  })
};

fetch('https://api2.scorecard.io/api/v2/attachments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

201

Upload needed

{
  "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"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

sessionId · string · required

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.

Required string length: 1 - 256

Example:

"c59e5bd0-e5eb-4bf0-a08a-01f7e8f712c7"

filePath · string · required

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.

Required string length: 1 - 1024

Example:

"/tmp/report.pdf"

sha256 · string · required

Lowercase hex SHA-256 of the file content.

Pattern: ^[0-9a-f]{64}$

Example:

"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"

sizeBytes · integer · required

Size of the file in bytes.

Required range: x >= 0

Example:

482133

contentType · string · required

MIME type of the file.

Required string length: 1 - 256

Example:

"application/pdf"

filename · string

Display filename. Defaults to none.

Required string length: 1 - 512

Example:

"report.pdf"

metadata · object

Arbitrary metadata to store with the attachment.

Response

201

application/json

Upload initiated (or content already stored). If alreadyExists is false, PUT the bytes to uploadUrl and then commit.

id · string<uuid> · required

The ID of the Attachment.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

alreadyExists · boolean · required

True if this exact content is already stored for this (session, file path) — no upload is needed and no upload URL is returned.

uploadUrl · string | null · required

Signed URL to PUT the file bytes to. Null when alreadyExists is true.

uploadMethod · enum<string> | null · required

HTTP method to use with uploadUrl.

Available options: PUT, null

expiresAt · string | null · required

ISO 8601 expiry of uploadUrl.