trezy.codes
forked from
slices.network/quickslice
Auto-indexing service and GraphQL API for AT Protocol Records
chadtmiller.com
1# Mutations
2
3Mutations write records to the authenticated user's repository. All mutations require authentication.
4
5## Creating Records
6
7```graphql
8mutation {
9 createXyzStatusphereStatus(
10 input: {
11 status: "🎉"
12 createdAt: "2025-01-30T12:00:00Z"
13 }
14 ) {
15 uri
16 status
17 createdAt
18 }
19}
20```
21
22Quickslice:
23
241. Writes the record to the user's PDS
252. Indexes locally for immediate query availability
26
27### Custom Record Keys
28
29By default, Quickslice generates a TID (timestamp-based ID) for the record key. You can specify a custom key:
30
31```graphql
32mutation {
33 createXyzStatusphereStatus(
34 input: {
35 status: "✨"
36 createdAt: "2025-01-30T12:00:00Z"
37 }
38 rkey: "my-custom-key"
39 ) {
40 uri
41 }
42}
43```
44
45Some Lexicons require specific key patterns. For example, profiles use `self` as the record key.
46
47## Updating Records
48
49Update an existing record by its record key:
50
51```graphql
52mutation {
53 updateXyzStatusphereStatus(
54 rkey: "3kvt7a2xyzw2a"
55 input: {
56 status: "🚀"
57 createdAt: "2025-01-30T12:00:00Z"
58 }
59 ) {
60 uri
61 status
62 }
63}
64```
65
66The update replaces the entire record. Include all required fields, not just the ones you're changing.
67
68## Deleting Records
69
70Delete a record by its record key:
71
72```graphql
73mutation {
74 deleteXyzStatusphereStatus(rkey: "3kvt7a2xyzw2a") {
75 uri
76 }
77}
78```
79
80## Working with Blobs
81
82Records can include binary data like images. Upload the blob first, then reference it.
83
84### Upload a Blob
85
86```graphql
87mutation {
88 uploadBlob(
89 data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
90 mimeType: "image/png"
91 ) {
92 ref
93 mimeType
94 size
95 }
96}
97```
98
99The `data` field accepts base64-encoded binary data. The response includes a `ref` (CID) for use in your record.
100
101### Use the Blob in a Record
102
103```graphql
104mutation {
105 updateAppBskyActorProfile(
106 rkey: "self"
107 input: {
108 displayName: "Alice"
109 avatar: {
110 ref: "bafkreiabc123..."
111 mimeType: "image/png"
112 size: 95
113 }
114 }
115 ) {
116 uri
117 displayName
118 avatar {
119 url(preset: "avatar")
120 }
121 }
122}
123```
124
125See the [Blobs Reference](../reference/blobs.md) for more details on blob handling and URL presets.
126
127## Error Handling
128
129Common mutation errors:
130
131| Error | Cause |
132|-------|-------|
133| `401 Unauthorized` | Missing or invalid authentication token |
134| `400 Bad Request` | Invalid input (missing required fields, wrong types) |
135| `404 Not Found` | Record doesn't exist (for update/delete) |
136| `403 Forbidden` | Trying to modify another user's record |
137
138## Authentication
139
140Mutations require authentication. Headers depend on the OAuth flow:
141
142**DPoP flow** (recommended for browser apps):
143```
144Authorization: DPoP <access_token>
145DPoP: <dpop_proof>
146```
147
148**Bearer token flow**:
149```
150Authorization: Bearer <access_token>
151```
152
153See the [Authentication Guide](authentication.md) for flow details and token acquisition.