Attachments

Issue attachments allow you to link external resources to issues and display them inside Linear similarly to GitHub Pull Requests. They are designed with API developers in mind and we also use them for upcoming integrations inside Linear.

Example use cases:

• Customer support software where an agent can create a Linear issue

• Release bot that attached release version to an issue

Unique URLs are a core concept with attachments. They enable building stateless applications and integrations which interact with Linear's API. Attachment URL is used as an idempotent value if used in conjunction with the same issue id so if you try to re-create an attachment with the same URL on the same issue, the original attachment is updated instead. This enables simple scripts which update the attachment content without storing the attachment ID. You can also query an attachment, and the associated issue, by its URL. This makes creating links to Linear issues from external application easy and again you don't need to track the attachment ID.

It's recommended to create attachments through Linear's OAuth authentication. Then the application icon is used for the attachment by default, but an icon image URL can be specified when creating the attachment that overrides the application icon. For API key auth, you can also provide an icon URL when creating an attachment. The image provided by URL must be of png or jpg format.

Attachments also support key-value metadata. Values can be any string or number and you can store information there related to your integration. Right now metadata is only exposed through the API but we're also considering exposing it in the UI.

Linear's webhooks also support attachments so you can subscribe to get updates for new and updated attachments.

Create an attachment:

mutation{
  attachmentCreate(input:{
    issueId: "590a1127-f98b-49fc-ba74-2df8751c089e"
    title: "Exception"
    subtitle: "Open"
    url: "http://exception.com/123"
    iconUrl: "https://exception.com/assets/icon.png"
    metadata: {exceptionId: "exc-123"}
  }){
    success
    attachment{
      id
    }
  }
}

Update an attachment with id:

mutation{
  attachmentUpdate(id: "47e14163-404c-4a34-b775-5c536d67760a", input: {
    title: "Exception"
    subtitle: "Resolved"
    metadata: {exceptionId: "exc-123"}
  }){
    success
    attachment{
      id
    }
  }
}

Query for attachments with a URL or for a specific attachment with an id:

query {
  attachment(id: "47e14163-404c-4a34-b775-5c536d67760a") {
    id
    issue {
      id
      identifier
      title
    }
  }
}
​
query {
  attachmentsForURL(url: "http://exception.com/123") {
    nodes {
      id
      issue {
        id
        identifier
        title
      }
    }
  }
}

Formatting

In order to use the date formatting, when creating an attachment provide a date variable (in ISO string format) in the attachment's metadata. You may then add that date with the format {variableName__since} into the attachment subtitle. When the attachment is rendered, we will format the time since that date, or format that date and time relative to current time, depending on which format is being used.

mutation{
  attachmentCreate(input:{
    issueId: "590a1127-f98b-49fc-ba74-2df8751c089e"
    title: "Exception"
    subtitle: "Detected {detectedAt__since}"
    url: "http://exception.com/123"
    iconUrl: "https://exception.com/assets/icon.png"
    metadata: {detectedAt: "2021-07-06T17:10:32.090Z"}
  }){
    success
    attachment{
      id
    }
  }
}

The above query would yield output like the following: