File Mutation

Upload File

uploadFile imports a file from a source URL and creates the Nolt file record. The complete workflow is:

1. Make the source file available at an HTTPS URL that Nolt's server can fetch without browser cookies or an interactive login.
2. Call uploadFile with that URL. Nolt retrieves the source, stores it, and returns the file record.

The mutation is not a binary-upload endpoint. If the file is not already available by URL, upload it to your own storage service first.

Required Headers

Header	Description
Content-Type: application/json	GraphQL requests use a JSON body
apikey	A write-enabled API key; it also scopes the request to a board
ssotype	SSO type for the user making the request
ssoid	SSO ID for the user making the request

Mutation Structure

mutation UploadFile(
  $url: String!
  $type: String!
  $filename: String
  $commentId: String
) {
  uploadFile(
    url: $url
    type: $type
    filename: $filename
    commentId: $commentId
  ) {
    id
    bytes
    cloudinaryId
    name
    url
    type
    version
    legacyUrl
    commentId
  }
}

Input Fields

Field	Type	Description
url	String!	Publicly fetchable source URL
type	String!	profile-image or comment
filename	String	Optional filename to use when storing the file
commentId	String	Required for comment; must identify an existing comment

Complete cURL Example

curl -X POST \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_API_KEY" \
  -H "ssotype: SSO" \
  -H "ssoid: USER_SSO_ID" \
  --data '{"query":"mutation UploadFile($url: String!, $type: String!, $filename: String, $commentId: String) { uploadFile(url: $url, type: $type, filename: $filename, commentId: $commentId) { id name url type commentId } }","variables":{"url":"https://files.example.com/screenshot.png","type":"comment","filename":"screenshot.png","commentId":"COMMENT_ID"}}' \
  https://api.nolt.io/api/v1/graphql

Profile Image

For profile-image, the ssotype and ssoid headers identify the existing board user whose profile image will be updated. Do not pass commentId.

mutation UploadProfileImage($url: String!, $filename: String) {
  uploadFile(url: $url, type: "profile-image", filename: $filename) {
    id
    name
    url
    type
  }
}

Comment Attachment

For comment, commentId is required. The mutation creates the association between the returned file and that comment.

mutation UploadCommentAttachment(
  $url: String!
  $filename: String
  $commentId: String!
) {
  uploadFile(
    url: $url
    type: "comment"
    filename: $filename
    commentId: $commentId
  ) {
    id
    name
    url
    type
    commentId
  }
}

Error Handling

The API returns GraphQL errors for an invalid or read-only API key, missing SSO headers, an unsupported type, a missing or unknown commentId, an unknown profile user, or a source URL that the upload service cannot fetch.