AT Protocol actor API
Actor (user) profile, search, and preference operations
OpenAPI Specification
openapi: 3.0.3
info:
title: Bluesky Application API (app.bsky) actor API
description: The Bluesky application-layer Lexicon API providing feed, actor, graph, notification, and video endpoints for the microblogging application built on AT Protocol. The AppView is accessible unauthenticated at public.api.bsky.app for read operations, and at api.bsky.app for authenticated write operations. Schemas are defined using Lexicon, AT Protocol's schema definition language.
version: 1.0.0
contact:
name: Bluesky
url: https://docs.bsky.app/
license:
name: MIT / Apache-2.0
url: https://github.com/bluesky-social/atproto/blob/main/LICENSE.txt
servers:
- url: https://public.api.bsky.app/xrpc
description: Public AppView (unauthenticated read operations)
- url: https://api.bsky.app/xrpc
description: Authenticated AppView (write operations)
security:
- bearerAuth: []
- {}
tags:
- name: actor
description: Actor (user) profile, search, and preference operations
paths:
/app.bsky.actor.getProfile:
get:
operationId: app_bsky_actor_getProfile
summary: Get Profile
description: Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
tags:
- actor
security:
- {}
- bearerAuth: []
parameters:
- name: actor
in: query
required: true
description: Handle or DID of account to fetch profile of.
schema:
type: string
responses:
'200':
description: Profile view
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileViewDetailed'
'400':
$ref: '#/components/responses/BadRequest'
/app.bsky.actor.getProfiles:
get:
operationId: app_bsky_actor_getProfiles
summary: Get Profiles
description: Get detailed profile views of multiple actors.
tags:
- actor
security:
- {}
- bearerAuth: []
parameters:
- name: actors
in: query
required: true
description: List of handles or DIDs to fetch profiles of. Maximum 25.
schema:
type: array
items:
type: string
maxItems: 25
style: form
explode: true
responses:
'200':
description: Profile views
content:
application/json:
schema:
type: object
required:
- profiles
properties:
profiles:
type: array
items:
$ref: '#/components/schemas/ProfileViewDetailed'
'400':
$ref: '#/components/responses/BadRequest'
/app.bsky.actor.searchActors:
get:
operationId: app_bsky_actor_searchActors
summary: Search Actors
description: Find actors (profiles) matching search criteria. Does not require auth.
tags:
- actor
security:
- {}
- bearerAuth: []
parameters:
- name: q
in: query
required: false
description: Search query string. Syntax, operators, and ranking of results subject to change.
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: cursor
in: query
required: false
schema:
type: string
responses:
'200':
description: Matching actors
content:
application/json:
schema:
type: object
required:
- actors
properties:
cursor:
type: string
actors:
type: array
items:
$ref: '#/components/schemas/ProfileView'
'400':
$ref: '#/components/responses/BadRequest'
/app.bsky.actor.getPreferences:
get:
operationId: app_bsky_actor_getPreferences
summary: Get Preferences
description: Get private preferences attached to the current account.
tags:
- actor
responses:
'200':
description: User preferences
content:
application/json:
schema:
type: object
required:
- preferences
properties:
preferences:
type: array
items:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/app.bsky.actor.putPreferences:
post:
operationId: app_bsky_actor_putPreferences
summary: Put Preferences
description: Set the private preferences attached to the account.
tags:
- actor
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- preferences
properties:
preferences:
type: array
items:
type: object
additionalProperties: true
responses:
'200':
description: Preferences updated
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/app.bsky.actor.getSuggestions:
get:
operationId: app_bsky_actor_getSuggestions
summary: Get Suggestions
description: Get a list of suggested actors (tending toward familiarity).
tags:
- actor
security:
- {}
- bearerAuth: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
required: false
schema:
type: string
responses:
'200':
description: Suggested actors
content:
application/json:
schema:
type: object
required:
- actors
properties:
cursor:
type: string
actors:
type: array
items:
$ref: '#/components/schemas/ProfileView'
components:
schemas:
Label:
type: object
required:
- src
- uri
- val
- cts
properties:
ver:
type: integer
src:
type: string
description: DID of the actor who created this label
uri:
type: string
description: AT URI of the record, repository (account), or other resource this label applies to
cid:
type: string
description: Optionally constrains label to specific version of record/blob
val:
type: string
description: The short string name of the value or type of this label
maxLength: 128
neg:
type: boolean
description: If true, this is a negation label, overwriting a previous label
cts:
type: string
format: date-time
description: Timestamp when this label was created
exp:
type: string
format: date-time
description: Timestamp at which this label expires
ProfileViewDetailed:
type: object
required:
- did
- handle
properties:
did:
type: string
description: Decentralized Identifier
handle:
type: string
description: User handle (e.g., user.bsky.social)
displayName:
type: string
maxLength: 640
description:
type: string
maxLength: 2560
avatar:
type: string
format: uri
banner:
type: string
format: uri
followersCount:
type: integer
followsCount:
type: integer
postsCount:
type: integer
associated:
type: object
description: Associated account data (lists, feeds, labeler, etc.)
additionalProperties: true
indexedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
viewer:
$ref: '#/components/schemas/ViewerState'
labels:
type: array
items:
$ref: '#/components/schemas/Label'
Error:
type: object
required:
- error
- message
properties:
error:
type: string
message:
type: string
ViewerState:
type: object
description: Metadata about the relationship between the requesting account and the subject account.
properties:
muted:
type: boolean
mutedByList:
type: object
additionalProperties: true
blockedBy:
type: boolean
blocking:
type: string
description: AT-URI of the blocking record, if present
blockingByList:
type: object
additionalProperties: true
following:
type: string
description: AT-URI of the follow record, if present
followedBy:
type: string
description: AT-URI of the follow record from the subject to the requester
knownFollowers:
type: object
additionalProperties: true
ProfileView:
type: object
required:
- did
- handle
properties:
did:
type: string
handle:
type: string
displayName:
type: string
description:
type: string
avatar:
type: string
format: uri
associated:
type: object
additionalProperties: true
indexedAt:
type: string
format: date-time
createdAt:
type: string
format: date-time
viewer:
$ref: '#/components/schemas/ViewerState'
labels:
type: array
items:
$ref: '#/components/schemas/Label'
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Bad request or validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Access JWT obtained from com.atproto.server.createSession
externalDocs:
description: Bluesky HTTP API Reference
url: https://docs.bsky.app/docs/advanced-guides/atproto