Attach URL card (Platform App)

Before You Begin

🔗 Use the GraphQL Playground to execute the mutations in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: The token’s user must be able to edit the target card (same authorization as the underlying resolver).
3. Platform app ID: The SUID of the Platform App that will own the attachment.
4. Card ID: The card SUID passed to cardId (the resolver loads the card with by_suid!).

Use the Get resource IDs page if you need help resolving IDs or UUIDs.

Mutation: attachUrlCard

This mutation registers a Platform App URL attachment on a card (label + URL). On the public API it lives on the root Mutation type (implemented in PlatformFields / app/graphql/types/root/root_mutations/platform_fields.rb), alongside other platform-related operations.

The GraphQL field name is attachUrlCard (from the Ruby field attach_url_card). Use that spelling in API v1 requests and clients.

Example (variables)

mutation attachUrlCard($input: AttachURLCardInput!) {
  attachUrlCard(input: $input) {
    attachment {
      id
      name
      url
      suid
      card_id
    }
  }
}

Variables (replace placeholders):

{
  "input": {
    "appId": "YOUR_PLATFORM_APP_SUID",
    "cardId": "YOUR_CARD_SUID",
    "name": "My app link",
    "url": "https://example.com/resource"
  }
}

Input fields

Response payload

Under attachUrlCard, the attachment object includes at least:

• id: Attachment identifier
• name, url: As provided
• suid: Attachment SUID
• card_id: Linked card’s numeric database ID (string in JSON), not the card SUID—this field is exposed with snake case in the schema

Response example (shape)

{
  "data": {
    "attachUrlCard": {
      "attachment": {
        "id": "123",
        "name": "My app link",
        "url": "https://example.com/resource",
        "suid": "abc-def-ghi",
        "card_id": "123456789"
      }
    }
  }
}

If the user cannot edit the card, or the app/card cannot be resolved, the API returns errors in the standard GraphQL errors array (for example permission denied or not found), and no attachment is created.

Notes

• Platform Apps vs file uploads: This flow is for app URL attachments, not the presigned S3 upload path described in Add attachments to a card or field.
• Internal API: The same operation was previously available on the internal GraphQL schema as attachURLCard; on API v1 use the root attachUrlCard mutation instead. The internal field is deprecated with reason Moved to APIV1 for improved schema organization.