Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bluesky-social/atproto/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The com.atproto.repo namespace provides lexicons for managing repositories and records in the AT Protocol. These are the core operations for creating, reading, updating, and deleting data.

​
Key Concepts

  • Repository: A versioned collection of records owned by a DID
  • Record: A piece of data stored in a repository (e.g., post, profile, follow)
  • Collection: A namespace for records (e.g., app.bsky.feed.post)
  • Record Key (rkey): Unique identifier for a record within a collection
  • Commit: A snapshot of the repository state
  • CID: Content Identifier for addressing data

​
Procedures

​
createRecord

Create a single new repository record. Endpoint: com.atproto.repo.createRecord Authentication: Required
​
repo
string
required
The handle or DID of the repo (current account)
​
collection
string
required
The NSID of the record collection (e.g., app.bsky.feed.post)
​
rkey
string
The Record Key (optional, will be auto-generated if omitted)
​
validate
boolean
Whether to validate the record against its lexicon schema. Defaults to validating only known lexicons.
​
record
object
required
The record data. Must contain a $type field matching the collection.
​
swapCommit
string
Compare-and-swap: only create if the repo’s current commit matches this CID
Response:
​
uri
string
required
AT-URI of the created record
​
cid
string
required
Content Identifier of the record
​
commit
object
Commit metadata (CID and revision)
​
validationStatus
string
Validation result: valid or unknown
Example: 
const response = await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  record: {
    $type: 'app.bsky.feed.post',
    text: 'Hello, AT Protocol!',
    createdAt: new Date().toISOString()
  }
})

console.log(response.data.uri)
// at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3k2y...

curl -X POST https://bsky.social/xrpc/com.atproto.repo.createRecord \
  -H "Authorization: Bearer $ACCESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "did:plc:...",
    "collection": "app.bsky.feed.post",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "Hello, AT Protocol!",
      "createdAt": "2024-03-04T12:00:00Z"
    }
  }'
Errors:
  • InvalidSwap: The swapCommit didn’t match current repo commit

​
putRecord

Write or update a repository record. Endpoint: com.atproto.repo.putRecord Authentication: Required Similar to createRecord, but uses a specific rkey and will overwrite existing records.
​
repo
string
required
The handle or DID of the repo
​
collection
string
required
The NSID of the record collection
​
rkey
string
required
The Record Key (required for put)
​
validate
boolean
Whether to validate the record
​
record
object
required
The record data
​
swapRecord
string
Compare-and-swap: only update if the current record CID matches
​
swapCommit
string
Compare-and-swap: only update if the repo’s current commit matches
Example: 
await agent.com.atproto.repo.putRecord({
  repo: agent.session.did,
  collection: 'app.bsky.actor.profile',
  rkey: 'self',
  record: {
    $type: 'app.bsky.actor.profile',
    displayName: 'Alice',
    description: 'Software engineer'
  }
})

​
deleteRecord

Delete a repository record. Endpoint: com.atproto.repo.deleteRecord Authentication: Required
​
repo
string
required
The handle or DID of the repo
​
collection
string
required
The NSID of the record collection
​
rkey
string
required
The Record Key to delete
​
swapRecord
string
Compare-and-swap: only delete if the current record CID matches
​
swapCommit
string
Compare-and-swap: only delete if the repo’s current commit matches
Example: 
await agent.com.atproto.repo.deleteRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  rkey: '3k2y...'
})

​
applyWrites

Apply a batch of repository writes (creates, updates, deletes) in a single commit. Endpoint: com.atproto.repo.applyWrites Authentication: Required
​
repo
string
required
The handle or DID of the repo
​
validate
boolean
Whether to validate records
​
writes
array
required
Array of write operations (create, update, delete)
​
swapCommit
string
Compare-and-swap commit CID
Example: 
await agent.com.atproto.repo.applyWrites({
  repo: agent.session.did,
  writes: [
    {
      $type: 'com.atproto.repo.applyWrites#create',
      collection: 'app.bsky.feed.post',
      value: {
        $type: 'app.bsky.feed.post',
        text: 'Post 1',
        createdAt: new Date().toISOString()
      }
    },
    {
      $type: 'com.atproto.repo.applyWrites#create',
      collection: 'app.bsky.feed.post',
      value: {
        $type: 'app.bsky.feed.post',
        text: 'Post 2',
        createdAt: new Date().toISOString()
      }
    }
  ]
})

​
uploadBlob

Upload a binary blob to the repository. Endpoint: com.atproto.repo.uploadBlob Authentication: Required Content-Type: Binary data (e.g., image/jpeg, video/mp4) Response:
​
blob
object
required
Blob reference with CID and metadata
Example: 
const response = await agent.com.atproto.repo.uploadBlob(
  imageData, // Uint8Array or Blob
  { encoding: 'image/jpeg' }
)

const blobRef = response.data.blob

// Use blob in a post
await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  record: {
    $type: 'app.bsky.feed.post',
    text: 'Check out this image!',
    embed: {
      $type: 'app.bsky.embed.images',
      images: [{
        image: blobRef,
        alt: 'A beautiful sunset'
      }]
    },
    createdAt: new Date().toISOString()
  }
})

​
Queries

​
getRecord

Get a single record from a repository. Endpoint: com.atproto.repo.getRecord
​
repo
string
required
The handle or DID of the repo
​
collection
string
required
The NSID of the record collection
​
rkey
string
required
The Record Key
​
cid
string
Optional: specific version of record to retrieve
Response:
​
uri
string
required
AT-URI of the record
​
cid
string
Content Identifier of the record
​
value
object
required
The record data
Example: 
const response = await agent.com.atproto.repo.getRecord({
  repo: 'alice.bsky.social',
  collection: 'app.bsky.feed.post',
  rkey: '3k2y...'
})

console.log(response.data.value.text)

​
listRecords

List records in a collection. Endpoint: com.atproto.repo.listRecords
​
repo
string
required
The handle or DID of the repo
​
collection
string
required
The NSID of the record collection
​
limit
integer
Maximum number of records to return (1-100, default 50)
​
cursor
string
Pagination cursor
​
reverse
boolean
Reverse chronological order
Response:
​
cursor
string
Pagination cursor for next page
​
records
array
required
Array of records with uri, cid, and value
Example: 
const response = await agent.com.atproto.repo.listRecords({
  repo: 'alice.bsky.social',
  collection: 'app.bsky.feed.post',
  limit: 25
})

for (const record of response.data.records) {
  console.log(record.value.text)
}

​
describeRepo

Get metadata about a repository. Endpoint: com.atproto.repo.describeRepo
​
repo
string
required
The handle or DID of the repo
Response:
​
handle
string
required
The repository handle
​
did
string
required
The repository DID
​
didDoc
object
required
The DID document
​
collections
array
required
List of collection NSIDs in the repo
​
handleIsCorrect
boolean
required
Whether the handle validates bi-directionally
Example: 
const response = await agent.com.atproto.repo.describeRepo({
  repo: 'alice.bsky.social'
})

console.log(response.data.collections)
// ['app.bsky.actor.profile', 'app.bsky.feed.post', 'app.bsky.graph.follow', ...]

​
importRepo

Import a CAR file repository. Endpoint: com.atproto.repo.importRepo Authentication: Required Used for account migration and backup restoration.

​
listMissingBlobs

List blobs that are referenced but missing from the repository. Endpoint: com.atproto.repo.listMissingBlobs Authentication: Required

​
Type Definitions

​
strongRef

A strong reference to a specific record version.
​
uri
string
required
AT-URI of the record
​
cid
string
required
Content Identifier of the specific version
Example: 
{
  uri: 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3k2y...',
  cid: 'bafyrei...'
}
Used for replies, quotes, and other references to specific content.

​
commitMeta

Metadata about a repository commit.
​
cid
string
required
Content Identifier of the commit
​
rev
string
required
Revision identifier (TID)

​
Common Use Cases

​
Creating a Post

const post = await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  record: {
    $type: 'app.bsky.feed.post',
    text: 'Hello World!',
    createdAt: new Date().toISOString()
  }
})

console.log('Post created:', post.data.uri)

​
Updating Profile

await agent.com.atproto.repo.putRecord({
  repo: agent.session.did,
  collection: 'app.bsky.actor.profile',
  rkey: 'self',
  record: {
    $type: 'app.bsky.actor.profile',
    displayName: 'Alice Smith',
    description: 'Software engineer and coffee enthusiast',
    avatar: blobRef // from uploadBlob
  }
})

​
Following a User

await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.graph.follow',
  record: {
    $type: 'app.bsky.graph.follow',
    subject: 'did:plc:...',
    createdAt: new Date().toISOString()
  }
})

​
Deleting a Post

await agent.com.atproto.repo.deleteRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  rkey: '3k2y...'
})

​
Resources