Mutations

Mutations write records to the authenticated user's repository. All mutations require authentication.

#Creating Records

mutation {
  createXyzStatusphereStatus(
    input: {
      status: "🎉"
      createdAt: "2025-01-30T12:00:00Z"
    }
  ) {
    uri
    status
    createdAt
  }
}

Quickslice:

1. Writes the record to the user's PDS
2. Indexes locally for immediate query availability

#Custom Record Keys

By default, Quickslice generates a TID (timestamp-based ID) for the record key. You can specify a custom key:

mutation {
  createXyzStatusphereStatus(
    input: {
      status: "✨"
      createdAt: "2025-01-30T12:00:00Z"
    }
    rkey: "my-custom-key"
  ) {
    uri
  }
}

Some Lexicons require specific key patterns. For example, profiles use self as the record key.

#Updating Records

Update an existing record by its record key:

mutation {
  updateXyzStatusphereStatus(
    rkey: "3kvt7a2xyzw2a"
    input: {
      status: "🚀"
      createdAt: "2025-01-30T12:00:00Z"
    }
  ) {
    uri
    status
  }
}

The update replaces the entire record. Include all required fields, not just the ones you're changing.

#Deleting Records

Delete a record by its record key:

mutation {
  deleteXyzStatusphereStatus(rkey: "3kvt7a2xyzw2a") {
    uri
  }
}

#Working with Blobs

Records can include binary data like images. Upload the blob first, then reference it.

#Upload a Blob

mutation {
  uploadBlob(
    data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    mimeType: "image/png"
  ) {
    ref
    mimeType
    size
  }
}

The data field accepts base64-encoded binary data. The response includes a ref (CID) for use in your record.

#Use the Blob in a Record

mutation {
  updateAppBskyActorProfile(
    rkey: "self"
    input: {
      displayName: "Alice"
      avatar: {
        ref: "bafkreiabc123..."
        mimeType: "image/png"
        size: 95
      }
    }
  ) {
    uri
    displayName
    avatar {
      url(preset: "avatar")
    }
  }
}

See the Blobs Reference for more details on blob handling and URL presets.

#Error Handling

Common mutation errors:

Error	Cause
401 Unauthorized	Missing or invalid authentication token
400 Bad Request	Invalid input (missing required fields, wrong types)
404 Not Found	Record doesn't exist (for update/delete)
403 Forbidden	Trying to modify another user's record

#Authentication

Mutations require authentication. Headers depend on the OAuth flow:

DPoP flow (recommended for browser apps):

Authorization: DPoP <access_token>
DPoP: <dpop_proof>

Bearer token flow:

Authorization: Bearer <access_token>

See the Authentication Guide for flow details and token acquisition.