+123

backend/src/api/feed.ts

reviewed

··· 1 1 + /* 2 2 + * clippr: a social bookmarking service for the AT Protocol 3 3 + * Copyright (c) 2025 clippr contributors. 4 4 + * SPDX-License-Identifier: AGPL-3.0-only 5 5 + */ 6 6 + 7 7 + import { 8 8 + SocialClipprActorDefs, 9 9 + SocialClipprFeedClip, 10 10 + SocialClipprFeedDefs, 11 11 + } from "@clipprjs/lexicons"; 12 12 + import type { ClipViewQuery, ErrorResponse, TagRef } from "./types.js"; 13 13 + import { getHandleFromDid } from "../network/converters.js"; 14 14 + import { Database } from "../db/database.js"; 15 15 + import { clipsTable } from "../db/schema.js"; 16 16 + import { and, eq } from "drizzle-orm"; 17 17 + import { createProfileView } from "./profile.js"; 18 18 + import { is } from "@atcute/lexicons"; 19 19 + import { validateHash } from "../hasher.js"; 20 20 + 21 21 + const db = Database.getInstance().getDb(); 22 22 + 23 23 + export async function createClipView( 24 24 + query: ClipViewQuery, 25 25 + ): Promise<SocialClipprFeedDefs.ClipView | ErrorResponse> { 26 26 + if (!query.did.startsWith("did:")) { 27 27 + let did; 28 28 + try { 29 29 + did = await getHandleFromDid(query.did); 30 30 + } catch (e: unknown) { 31 31 + if (e instanceof Error) { 32 32 + return { 33 33 + error: "InvalidRequest", 34 34 + message: `Error: A queried URI does not have a valid DID or handle: ${e.message}`, 35 35 + }; 36 36 + } else { 37 37 + return { 38 38 + error: "InvalidRequest", 39 39 + message: 40 40 + "Error: A queried URI does not have a valid DID or handle: unknown error", 41 41 + }; 42 42 + } 43 43 + } 44 44 + query.did = did; 45 45 + } 46 46 + 47 47 + if (query.collection !== "social.clippr.feed.clip") { 48 48 + return { 49 49 + error: "InvalidRequest", 50 50 + message: "Error: A queried URI is not a proper clip", 51 51 + }; 52 52 + } 53 53 + 54 54 + const dbQuery = await db 55 55 + .selectDistinct() 56 56 + .from(clipsTable) 57 57 + .where( 58 58 + and( 59 59 + eq(clipsTable.did, query.did), 60 60 + eq(clipsTable.recordKey, query.recordKey), 61 61 + ), 62 62 + ); 63 63 + 64 64 + if (dbQuery.length === 0) { 65 65 + return { 66 66 + error: "InvalidRequest", 67 67 + message: "Could not find a given URI", 68 68 + }; 69 69 + } 70 70 + 71 71 + // Yes, the array thing is not ideal. 72 72 + if (!dbQuery[0]?.cid) { 73 73 + return { 74 74 + error: "InvalidRequest", 75 75 + message: "Could not find a given URI", 76 76 + }; 77 77 + } 78 78 + 79 79 + if (!(await validateHash(dbQuery[0]?.url, query.recordKey))) { 80 80 + return { 81 81 + error: "InvalidRequest", 82 82 + message: "Could not find a given URI", 83 83 + }; 84 84 + } 85 85 + 86 86 + const authorView: ErrorResponse | SocialClipprActorDefs.ProfileView = 87 87 + await createProfileView(query.did); 88 88 + 89 89 + if (!is(SocialClipprActorDefs.profileViewSchema, authorView)) { 90 90 + console.log(authorView); 91 91 + return { 92 92 + error: "InvalidRequest", 93 93 + message: "Could not validate profile view", // I can't get the error message, it seems to always assume the type is the ProfileView 94 94 + } as ErrorResponse; 95 95 + } 96 96 + 97 97 + let clipTags: TagRef[] | undefined; 98 98 + 99 99 + if (dbQuery[0]?.tags === null) { 100 100 + clipTags = undefined; 101 101 + } 102 102 + 103 103 + const clipRecord: SocialClipprFeedClip.Main = { 104 104 + $type: "social.clippr.feed.clip", 105 105 + url: dbQuery[0]?.url as `${string}:${string}`, 106 106 + title: dbQuery[0]?.title, 107 107 + description: dbQuery[0]?.description, 108 108 + tags: clipTags || undefined, 109 109 + unlisted: dbQuery[0]?.unlisted, 110 110 + unread: dbQuery[0]?.unread || undefined, 111 111 + notes: dbQuery[0]?.notes || undefined, 112 112 + languages: dbQuery[0]?.languages || undefined, 113 113 + createdAt: dbQuery[0]?.createdAt.toISOString(), 114 114 + }; 115 115 + 116 116 + return { 117 117 + cid: dbQuery[0]?.cid, 118 118 + uri: `at://${query.did}/${query.collection}/${query.recordKey}`, 119 119 + author: authorView, 120 120 + record: clipRecord, 121 121 + indexedAt: dbQuery[0]?.indexedAt.toISOString(), 122 122 + }; 123 123 + }

+101

backend/src/api/profile.ts

reviewed

··· 1 1 + /* 2 2 + * clippr: a social bookmarking service for the AT Protocol 3 3 + * Copyright (c) 2025 clippr contributors. 4 4 + * SPDX-License-Identifier: AGPL-3.0-only 5 5 + */ 6 6 + 7 7 + import { SocialClipprActorDefs } from "@clipprjs/lexicons"; 8 8 + import type { ErrorResponse } from "./types.js"; 9 9 + import { getDidFromHandle, getHandleFromDid } from "../network/converters.js"; 10 10 + import { Database } from "../db/database.js"; 11 11 + import { usersTable } from "../db/schema.js"; 12 12 + import { eq } from "drizzle-orm"; 13 13 + 14 14 + const db = Database.getInstance().getDb(); 15 15 + 16 16 + // TODO: Stop leeching off the Bluesky CDN and get the blob directly from the user's PDS 17 17 + // 18 18 + // Get a CDN URI from a blob's CID 19 19 + export async function createAvatarLink( 20 20 + did: string, 21 21 + cid: string, 22 22 + ): Promise<string> { 23 23 + return `https://cdn.bsky.app/img/avatar/plain/${did}/${cid}`; 24 24 + } 25 25 + 26 26 + export async function createProfileView( 27 27 + actor: string, 28 28 + ): Promise<SocialClipprActorDefs.ProfileView | ErrorResponse> { 29 29 + let viewHandle; 30 30 + let viewDid; 31 31 + 32 32 + if (actor.startsWith("did:")) { 33 33 + viewDid = actor; 34 34 + try { 35 35 + viewHandle = await getHandleFromDid(viewDid); 36 36 + viewHandle = viewHandle.replace("at://", ""); 37 37 + } catch (e: unknown) { 38 38 + if (e instanceof Error) { 39 39 + return { 40 40 + error: "InvalidRequest", 41 41 + message: `Error: A queried URI does not have a valid DID or handle: ${e.message}`, 42 42 + }; 43 43 + } else { 44 44 + return { 45 45 + error: "InvalidRequest", 46 46 + message: 47 47 + "Error: A queried URI does not have a valid DID or handle: unknown error", 48 48 + }; 49 49 + } 50 50 + } 51 51 + } else { 52 52 + viewHandle = actor; 53 53 + viewHandle = viewHandle.replace("at://", ""); 54 54 + try { 55 55 + viewDid = await getDidFromHandle(viewHandle); 56 56 + } catch (e: unknown) { 57 57 + if (e instanceof Error) { 58 58 + return { 59 59 + error: "InvalidRequest", 60 60 + message: `Error: A queried URI does not have a valid DID or handle: ${e.message}`, 61 61 + }; 62 62 + } else { 63 63 + return { 64 64 + error: "InvalidRequest", 65 65 + message: 66 66 + "Error: A queried URI does not have a valid DID or handle: unknown error", 67 67 + }; 68 68 + } 69 69 + } 70 70 + } 71 71 + 72 72 + const dbQuery = await db 73 73 + .selectDistinct() 74 74 + .from(usersTable) 75 75 + .where(eq(usersTable.did, viewDid)); 76 76 + 77 77 + if (dbQuery.length === 0) { 78 78 + return { 79 79 + error: "InvalidRequest", 80 80 + message: "Could not find a queried URI's profile", 81 81 + } as ErrorResponse; 82 82 + } 83 83 + 84 84 + const avatarCid = dbQuery[0]?.avatar; 85 85 + 86 86 + let viewAvatar; 87 87 + 88 88 + if (avatarCid === undefined || avatarCid === null) { 89 89 + viewAvatar = "https://missing.avatar"; 90 90 + } else viewAvatar = await createAvatarLink(viewDid, avatarCid); 91 91 + 92 92 + return { 93 93 + $type: "social.clippr.actor.defs#profileView", 94 94 + did: viewDid as `did:${string}:${string}`, 95 95 + handle: viewHandle as `${string}.${string}`, 96 96 + avatar: (viewAvatar as `${string}:${string}`) || undefined, 97 97 + createdAt: dbQuery[0]?.createdAt.toISOString(), 98 98 + description: dbQuery[0]?.description || undefined, 99 99 + displayName: dbQuery[0]?.displayName || viewHandle, 100 100 + }; 101 101 + }

+38

backend/src/api/types.ts

reviewed

··· 1 1 + /* 2 2 + * clippr: a social bookmarking service for the AT Protocol 3 3 + * Copyright (c) 2025 clippr contributors. 4 4 + * SPDX-License-Identifier: AGPL-3.0-only 5 5 + */ 6 6 + 7 7 + import type { ResourceUri } from "@atcute/lexicons"; 8 8 + 9 9 + export interface ErrorResponse { 10 10 + error: string; 11 11 + message: string; 12 12 + } 13 13 + 14 14 + export interface ProfileViewQuery { 15 15 + actor: string; 16 16 + } 17 17 + 18 18 + export interface ClipViewQuery { 19 19 + did: string; 20 20 + collection: string; 21 21 + recordKey: string; 22 22 + } 23 23 + 24 24 + export const isClipViewQuery = (query: unknown): query is ClipViewQuery => { 25 25 + return typeof query === "object" && query !== null && "did" in query; 26 26 + }; 27 27 + 28 28 + export interface TagRef { 29 29 + $type: "com.atproto.repo.strongRef"; 30 30 + cid: string; 31 31 + uri: ResourceUri; 32 32 + } 33 33 + 34 34 + export interface TagViewQuery { 35 35 + did: string; 36 36 + collection: string; 37 37 + recordKey: string; 38 38 + }

+3 -2

backend/src/db/schema.ts

reviewed

··· 6 6 7 7 import { int, sqliteTable, text } from "drizzle-orm/sqlite-core"; 8 8 import { sql } from "drizzle-orm"; 9 9 + import type { TagRef } from "../api/types.js"; 9 10 10 11 // WebStorm keeps throwing errors with the default statements as it wants 11 12 // an actual SQLite query, despite being valid. Sucks. ··· 23 24 unlisted: int("unlisted", { mode: "boolean" }).notNull(), 24 25 notes: text("notes"), 25 26 tags: text("tags", { mode: "json" }) 26 26 - .$type<string[]>() 27 27 + .$type<TagRef[]>() 27 28 .default(sql`'[]'`), 28 29 unread: int("unread", { mode: "boolean" }), 29 30 languages: text("languages", { mode: "json" }) ··· 63 64 .default(sql`(unixepoch() * 1000)`), 64 65 did: text("did").notNull().unique(), 65 66 cid: text("cid").notNull(), 66 66 - displayName: text("displayName"), 67 67 + displayName: text("displayName").notNull(), 67 68 description: text("description"), 68 69 avatar: text("avatar"), 69 70 createdAt: int("createdAt", { mode: "timestamp_ms" })

+21

backend/src/hasher.ts

reviewed

··· 1 1 + /* 2 2 + * clippr: a social bookmarking service for the AT Protocol 3 3 + * Copyright (c) 2025 clippr contributors. 4 4 + * SPDX-License-Identifier: AGPL-3.0-only 5 5 + */ 6 6 + 7 7 + import xxhash from "xxhash-wasm"; 8 8 + 9 9 + /// Hash a given string into a hexadecimal xxh64 string. 10 10 + export async function hashString(data: string): Promise<string> { 11 11 + const { h64 } = await xxhash(); 12 12 + return h64(data).toString(16); 13 13 + } 14 14 + 15 15 + /// Check if a string is equivalent to a given hash. 16 16 + export async function validateHash( 17 17 + data: string, 18 18 + hash: string, 19 19 + ): Promise<boolean> { 20 20 + return hash === (await hashString(data)); 21 21 + }

+2 -3

backend/src/network/commit.ts

reviewed

··· 16 16 import Logger from "../logger.js"; 17 17 import { isBlob } from "@atcute/lexicons/interfaces"; 18 18 import { validateClip, validateProfile, validateTag } from "./validator.js"; 19 19 - import xxhash from "xxhash-wasm"; 20 19 import { convertDidToString } from "./converters.js"; 20 20 + import { hashString } from "../hasher.js"; 21 21 22 22 const db = Database.getInstance().getDb(); 23 23 ··· 65 65 }; 66 66 67 67 // xxh64, NOT xxh3 learned that the hard way 68 68 - const { h64 } = await xxhash(); 69 69 - const urlHash = h64(record.url).toString(16); 68 68 + const urlHash: string = await hashString(record.url); 70 69 71 70 if (urlHash !== event.commit.rkey) { 72 71 Logger.verbose(

-9

backend/src/network/converters.ts

reviewed

··· 31 31 } 32 32 } 33 33 34 34 - // TODO: Stop leeching off the Bluesky CDN and get the blob directly from the user's PDS 35 35 - // Get a CDN URI from a blob's CID 36 36 - export async function getUriFromBlobCid( 37 37 - did: string, 38 38 - cid: string, 39 39 - ): Promise<string> { 40 40 - return `https://cdn.bsky.app/img/avatar/plain/${did}/${cid}`; 41 41 - } 42 42 - 43 34 // Get a user's handle from their DID. DID method agnostic. 44 35 export async function getHandleFromDid(did: string): Promise<string> { 45 36 const docResolver = new CompositeDidDocumentResolver({

+114 -6

backend/src/routes/xrpc.ts

reviewed

··· 8 8 import { Database } from "../db/database.js"; 9 9 import { usersTable } from "../db/schema.js"; 10 10 import { eq } from "drizzle-orm"; 11 11 - import { 12 12 - getDidFromHandle, 13 13 - getHandleFromDid, 14 14 - getUriFromBlobCid, 15 15 - } from "../network/converters.js"; 11 11 + import { getDidFromHandle, getHandleFromDid } from "../network/converters.js"; 12 12 + import { createClipView } from "../api/feed.js"; 13 13 + import { type ClipViewQuery, type ErrorResponse } from "../api/types.js"; 14 14 + import { createAvatarLink } from "../api/profile.js"; 15 15 + import { SocialClipprFeedDefs } from "@clipprjs/lexicons"; 16 16 + import { is } from "@atcute/lexicons"; 16 17 17 18 const app = new Hono(); 18 19 const db = Database.getInstance().getDb(); ··· 101 102 } else actorHandle = actor; 102 103 103 104 // TODO: Add placeholder avatar 105 105 + // This is a mess and should be replaced with a real solution! 104 106 const avatarCid: string = 105 107 profileSearch[0]?.avatar || "https://missing.avatar"; 106 108 let actorAvatar; 107 109 if (avatarCid !== "https://missing.avatar") { 108 108 - actorAvatar = await getUriFromBlobCid(actorDid, avatarCid); 110 110 + actorAvatar = await createAvatarLink(actorDid, avatarCid); 109 111 } else actorAvatar = avatarCid; 110 112 111 113 // Right now we don't do de-duplication in the database, so we just take the ··· 118 120 description: profileSearch[0]?.description || null, 119 121 createdAt: profileSearch[0]?.createdAt, 120 122 }); 123 123 + }); 124 124 + 125 125 + app.get("/social.clippr.feed.getClips", async (c) => { 126 126 + const uris = c.req.query("uris"); 127 127 + if (uris === undefined || uris.trim().length === 0) { 128 128 + return c.json( 129 129 + { 130 130 + error: "InvalidRequest", 131 131 + message: "Error: Parameters must have the uris property included", 132 132 + }, 133 133 + 400, 134 134 + ); 135 135 + } 136 136 + 137 137 + const rawUriArray: string[] = uris.split(","); 138 138 + 139 139 + if (rawUriArray.length > 25) { 140 140 + return c.json( 141 141 + { 142 142 + error: "InvalidRequest", 143 143 + message: "Error: More than 25 URIs have been provided", 144 144 + }, 145 145 + 400, 146 146 + ); 147 147 + } 148 148 + 149 149 + if ( 150 150 + rawUriArray.some((value) => { 151 151 + return !value.startsWith("at://"); 152 152 + }) 153 153 + ) { 154 154 + return c.json( 155 155 + { 156 156 + error: "InvalidRequest", 157 157 + message: "Error: A queried URI is missing the at:// identifier", 158 158 + }, 159 159 + 400, 160 160 + ); 161 161 + } 162 162 + 163 163 + const parsedUriArray: object[] = []; 164 164 + 165 165 + for (let value of rawUriArray) { 166 166 + value = value.replace("at://", ""); 167 167 + const splitUri: string[] = value.split("/"); 168 168 + 169 169 + if (splitUri.length !== 3) { 170 170 + c.json( 171 171 + { 172 172 + error: "InvalidRequest", 173 173 + message: "Error: A queried URI is not a proper clip", 174 174 + }, 175 175 + 400, 176 176 + ); 177 177 + } 178 178 + 179 179 + let splitUriObject: ClipViewQuery = { 180 180 + did: "", 181 181 + collection: "", 182 182 + recordKey: "", 183 183 + }; 184 184 + 185 185 + // validate type 186 186 + if ( 187 187 + !splitUri[0] || 188 188 + !splitUri[1] || 189 189 + !splitUri[2] || 190 190 + typeof splitUri[0] !== "string" || 191 191 + typeof splitUri[1] !== "string" || 192 192 + typeof splitUri[2] !== "string" 193 193 + ) { 194 194 + c.json( 195 195 + { 196 196 + error: "InvalidRequest", 197 197 + message: "Error: A queried URI is not a proper clip", 198 198 + }, 199 199 + 400, 200 200 + ); 201 201 + } else { 202 202 + splitUriObject = { 203 203 + did: splitUri[0], 204 204 + collection: splitUri[1], 205 205 + recordKey: splitUri[2], 206 206 + }; 207 207 + } 208 208 + 209 209 + const clipView = await createClipView(splitUriObject); 210 210 + 211 211 + if (!is(SocialClipprFeedDefs.clipViewSchema, value)) { 212 212 + c.json(clipView, 400); 213 213 + } 214 214 + 215 215 + parsedUriArray.push(clipView); 216 216 + } 217 217 + 218 218 + if (parsedUriArray.length === 0) { 219 219 + return c.json( 220 220 + { 221 221 + error: "InvalidRequest", 222 222 + message: "No queried URIs exist", 223 223 + } as ErrorResponse, 224 224 + 400, 225 225 + ); 226 226 + } 227 227 + 228 228 + return c.json(parsedUriArray, 200); 121 229 }); 122 230 123 231 app.get("/_health", async (c) => {

+1226 -1290

backend/static/api.json

reviewed

··· 1 1 { 2 2 - "openapi": "3.1.1", 3 3 - "info": { 4 4 - "title": "Clippr AppView API", 5 5 - "version": "1.0.1", 6 6 - "description": "API reference documentation for Clippr's backend.", 7 7 - "license": { 8 8 - "name": "GNU Affero General Public License v3.0 only", 9 9 - "identifier": "AGPL-3.0-only" 10 10 - } 11 11 - }, 12 12 - "servers": [ 13 13 - { 14 14 - "url": "http://localhost:9090", 15 15 - "description": "Development server" 16 16 - }, 17 17 - { 18 18 - "url": "https://api.clippr.social", 19 19 - "description": "Production server" 20 20 - } 21 21 - ], 22 22 - "tags": [ 23 23 - { 24 24 - "name": "Clips", 25 25 - "description": "API paths that relate to user bookmarks, or 'clips'." 26 26 - }, 27 27 - { 28 28 - "name": "Tags", 29 29 - "description": "API paths that relate to user tags." 30 30 - }, 31 31 - { 32 32 - "name": "Profile", 33 33 - "description": "API paths that relate to user profiles." 34 34 - }, 35 35 - { 36 36 - "name": "Misc", 37 37 - "description": "API paths that don't fit into any other category." 38 38 - } 39 39 - ], 40 40 - "paths": { 41 41 - "/xrpc/social.clippr.actor.getPreferences": { 42 42 - "get": { 43 43 - "tags": [ 44 44 - "Profile" 45 45 - ], 46 46 - "summary": "Get a user's preferences", 47 47 - "operationId": "social.clippr.actor.getPreferences", 48 48 - "description": "Get a user's private preferences. Requires authentication.", 49 49 - "security": [ 50 50 - { 51 51 - "Bearer": [] 52 52 - } 53 53 - ], 54 54 - "responses": { 55 55 - "200": { 56 56 - "description": "OK", 57 57 - "content": { 58 58 - "application/json": { 59 59 - "schema": { 60 60 - "$ref": "#/components/schemas/social.clippr.actor.defs.preferences" 61 61 - } 62 62 - } 63 63 - } 64 64 - }, 65 65 - "400": { 66 66 - "description": "Bad Request", 67 67 - "content": { 68 68 - "application/json": { 69 69 - "schema": { 70 70 - "type": "object", 71 71 - "properties": { 72 72 - "error": { 73 73 - "type": "string", 74 74 - "description": "A general error code", 75 75 - "oneOf": [ 76 76 - { 77 77 - "const": "InvalidRequest" 78 78 - }, 79 79 - { 80 80 - "const": "ExpiredToken" 81 81 - }, 82 82 - { 83 83 - "const": "InvalidToken" 84 84 - } 85 85 - ] 86 86 - }, 87 87 - "message": { 88 88 - "type": "string", 89 89 - "description": "A detailed description of the error" 90 90 - } 91 91 - } 92 92 - } 93 93 - } 94 94 - } 95 95 - }, 96 96 - "401": { 97 97 - "description": "Unauthorized", 98 98 - "content": { 99 99 - "application/json": { 100 100 - "schema": { 101 101 - "type": "object", 102 102 - "properties": { 103 103 - "error": { 104 104 - "type": "string", 105 105 - "description": "A general error code", 106 106 - "oneOf": [ 107 107 - { 108 108 - "const": "AuthMissing" 109 109 - } 110 110 - ] 111 111 - }, 112 112 - "message": { 113 113 - "type": "string", 114 114 - "description": "A detailed description of the error" 115 115 - } 116 116 - } 117 117 - } 118 118 - } 119 119 - } 120 120 - } 121 121 - } 122 122 - } 123 123 - }, 124 124 - "/xrpc/social.clippr.actor.getProfile": { 125 125 - "get": { 126 126 - "tags": [ 127 127 - "Profile" 128 128 - ], 129 129 - "summary": "Get a profile", 130 130 - "operationId": "social.clippr.actor.getProfile", 131 131 - "description": "Get a user's profile based on a given DID or handle.", 132 132 - "parameters": [ 133 133 - { 134 134 - "name": "actor", 135 135 - "in": "query", 136 136 - "description": "Handle or DID of account to fetch profile of", 137 137 - "required": true, 138 138 - "content": { 139 139 - "schema": { 140 140 - "type": "string", 141 141 - "description": "Handle or DID of account to fetch profile of", 142 142 - "format": "at-identifier" 143 143 - } 144 144 - }, 145 145 - "deprecated": false, 146 146 - "allowEmptyValue": false 147 147 - } 148 148 - ], 149 149 - "responses": { 150 150 - "200": { 151 151 - "description": "OK", 152 152 - "content": { 153 153 - "application/json": { 154 154 - "schema": { 155 155 - "type": "object", 156 156 - "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 157 157 - } 158 158 - } 159 159 - } 160 160 - }, 161 161 - "400": { 162 162 - "description": "Bad Request", 163 163 - "content": { 164 164 - "application/json": { 165 165 - "schema": { 166 166 - "type": "object", 167 167 - "properties": { 168 168 - "error": { 169 169 - "type": "string", 170 170 - "description": "A general error code", 171 171 - "oneOf": [ 172 172 - { 173 173 - "const": "InvalidRequest" 174 174 - } 175 175 - ] 176 176 - }, 177 177 - "message": { 178 178 - "type": "string", 179 179 - "description": "A detailed description of the error" 180 180 - } 181 181 - } 182 182 - } 183 183 - } 184 184 - } 185 185 - } 186 186 - } 187 187 - } 188 188 - }, 189 189 - "/xrpc/social.clippr.actor.putPreferences": { 190 190 - "post": { 191 191 - "tags": [ 192 192 - "Profile" 193 193 - ], 194 194 - "summary": "Set a user's preferences", 195 195 - "operationId": "social.clippr.actor.putPreferences", 196 196 - "description": "Sets the private preferences attached to the account. Requires authentication.", 197 197 - "security": [ 198 198 - { 199 199 - "Bearer": [] 200 200 - } 201 201 - ], 202 202 - "requestBody": { 203 203 - "required": true, 204 204 - "content": { 205 205 - "application/json": { 206 206 - "schema": { 207 207 - "type": "object", 208 208 - "properties": { 209 209 - "preferences": { 210 210 - "$ref": "#/components/schemas/social.clippr.actor.defs.preferences" 211 211 - } 212 212 - } 213 213 - } 214 214 - } 215 215 - } 216 216 - }, 217 217 - "responses": { 218 218 - "200": { 219 219 - "description": "OK" 220 220 - }, 221 221 - "400": { 222 222 - "description": "Bad Request", 223 223 - "content": { 224 224 - "application/json": { 225 225 - "schema": { 226 226 - "type": "object", 227 227 - "properties": { 228 228 - "error": { 229 229 - "type": "string", 230 230 - "oneOf": [ 231 231 - { 232 232 - "const": "InvalidRequest" 233 233 - }, 234 234 - { 235 235 - "const": "ExpiredToken" 236 236 - }, 237 237 - { 238 238 - "const": "InvalidToken" 239 239 - } 240 240 - ], 241 241 - "description": "A general error code" 242 242 - }, 243 243 - "message": { 244 244 - "type": "string", 245 245 - "description": "A detailed description of the error" 246 246 - } 247 247 - } 248 248 - } 249 249 - } 250 250 - } 251 251 - }, 252 252 - "401": { 253 253 - "description": "Unauthorized", 254 254 - "content": { 255 255 - "application/json": { 256 256 - "schema": { 257 257 - "type": "object", 258 258 - "properties": { 259 259 - "error": { 260 260 - "type": "string", 261 261 - "description": "A general error code", 262 262 - "oneOf": [ 263 263 - { 264 264 - "const": "AuthMissing" 265 265 - } 266 266 - ] 267 267 - }, 268 268 - "message": { 269 269 - "type": "string", 270 270 - "description": "A detailed description of the error" 271 271 - } 272 272 - } 273 273 - } 274 274 - } 275 275 - } 276 276 - } 277 277 - } 278 278 - } 279 279 - }, 280 280 - "/xrpc/social.clippr.actor.searchClips": { 281 281 - "get": { 282 282 - "tags": [ 283 283 - "Clips" 284 284 - ], 285 285 - "summary": "Search clips", 286 286 - "operationId": "social.clippr.actor.searchClips", 287 287 - "description": "Find clips matching search criteria.", 288 288 - "parameters": [ 289 289 - { 290 290 - "name": "q", 291 291 - "in": "query", 292 292 - "description": "Search query string", 293 293 - "required": true, 294 294 - "schema": { 295 295 - "type": "string", 296 296 - "description": "Search query string" 297 297 - } 298 298 - }, 299 299 - { 300 300 - "name": "limit", 301 301 - "in": "query", 302 302 - "description": "How many clips to return in the query output", 303 303 - "required": false, 304 304 - "schema": { 305 305 - "type": "integer", 306 306 - "minimum": 1, 307 307 - "maximum": 100, 308 308 - "default": 25 309 309 - } 310 310 - }, 311 311 - { 312 312 - "name": "actor", 313 313 - "in": "query", 314 314 - "description": "An actor to filter results to", 315 315 - "required": false, 316 316 - "schema": { 317 317 - "type": "string", 318 318 - "description": "An actor to filter results to", 319 319 - "format": "at-identifier" 320 320 - } 321 321 - }, 322 322 - { 323 323 - "name": "cursor", 324 324 - "in": "query", 325 325 - "description": "A parameter to paginate results", 326 326 - "required": false, 327 327 - "schema": { 328 328 - "type": "string", 329 329 - "description": "A parameter to paginate results" 330 330 - } 331 331 - } 332 332 - ], 333 333 - "responses": { 334 334 - "200": { 335 335 - "description": "OK", 336 336 - "content": { 337 337 - "application/json": { 338 338 - "schema": { 339 339 - "type": "object", 340 340 - "properties": { 341 341 - "cursor": { 342 342 - "type": "string", 343 343 - "description": "A parameter to paginate results" 344 344 - }, 345 345 - "clips": { 346 346 - "type": "array", 347 347 - "items": { 348 348 - "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 349 349 - } 350 350 - } 351 351 - } 352 352 - } 353 353 - } 354 354 - } 355 355 - }, 356 356 - "400": { 357 357 - "description": "Bad Request", 358 358 - "content": { 359 359 - "application/json": { 360 360 - "schema": { 361 361 - "type": "object", 362 362 - "properties": { 363 363 - "error": { 364 364 - "type": "string", 365 365 - "description": "A general error code", 366 366 - "oneOf": [ 367 367 - { 368 368 - "const": "InvalidRequest" 369 369 - } 370 370 - ] 371 371 - }, 372 372 - "message": { 373 373 - "type": "string", 374 374 - "description": "A detailed description of the error" 375 375 - } 376 376 - } 377 377 - } 378 378 - } 379 379 - } 380 380 - } 381 381 - } 382 382 - } 383 383 - }, 384 384 - "/xrpc/social.clippr.actor.searchProfiles": { 385 385 - "get": { 386 386 - "tags": [ 387 387 - "Profile" 388 388 - ], 389 389 - "summary": "Search profiles", 390 390 - "operationId": "social.clippr.actor.searchProfiles", 391 391 - "description": "Find profiles matching search criteria.", 392 392 - "parameters": [ 393 393 - { 394 394 - "name": "q", 395 395 - "in": "query", 396 396 - "description": "Search query string", 397 397 - "required": false, 398 398 - "schema": { 399 399 - "type": "string", 400 400 - "description": "Search query string" 401 401 - } 402 402 - }, 403 403 - { 404 404 - "name": "limit", 405 405 - "in": "query", 406 406 - "description": "The number of profiles to be returned in the query", 407 407 - "required": false, 408 408 - "schema": { 409 409 - "type": "integer", 410 410 - "minimum": 1, 411 411 - "maximum": 100, 412 412 - "default": 25 413 413 - } 414 414 - }, 415 415 - { 416 416 - "name": "cursor", 417 417 - "in": "query", 418 418 - "description": "A parameter used for pagination", 419 419 - "required": false, 420 420 - "schema": { 421 421 - "type": "string", 422 422 - "description": "A parameter used for pagination" 423 423 - } 424 424 - } 425 425 - ], 426 426 - "responses": { 427 427 - "200": { 428 428 - "description": "OK", 429 429 - "content": { 430 430 - "application/json": { 431 431 - "schema": { 432 432 - "type": "object", 433 433 - "properties": { 434 434 - "cursor": { 435 435 - "type": "string", 436 436 - "description": "A parameter used for pagination" 437 437 - }, 438 438 - "actors": { 439 439 - "type": "array", 440 440 - "items": { 441 441 - "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 442 442 - } 443 443 - } 444 444 - } 445 445 - } 446 446 - } 447 447 - } 448 448 - }, 449 449 - "400": { 450 450 - "description": "Bad Request", 451 451 - "content": { 452 452 - "application/json": { 453 453 - "schema": { 454 454 - "type": "object", 455 455 - "properties": { 456 456 - "error": { 457 457 - "type": "string", 458 458 - "description": "A general error code", 459 459 - "oneOf": [ 460 460 - { 461 461 - "const": "InvalidRequest" 462 462 - } 463 463 - ] 464 464 - }, 465 465 - "message": { 466 466 - "type": "string", 467 467 - "description": "A detailed description of the error" 468 468 - } 469 469 - } 470 470 - } 471 471 - } 472 472 - } 473 473 - } 474 474 - } 475 475 - } 476 476 - }, 477 477 - "/xrpc/social.clippr.actor.searchTags": { 478 478 - "get": { 479 479 - "tags": [ 480 480 - "Tags" 481 481 - ], 482 482 - "summary": "Search tags", 483 483 - "operationId": "social.clippr.actor.searchTags", 484 484 - "description": "Find tags matching search criteria.", 485 485 - "parameters": [ 486 486 - { 487 487 - "name": "q", 488 488 - "in": "query", 489 489 - "description": "Search query string", 490 490 - "required": true, 491 491 - "schema": { 492 492 - "type": "string", 493 493 - "description": "Search query string" 494 494 - } 495 495 - }, 496 496 - { 497 497 - "name": "limit", 498 498 - "in": "query", 499 499 - "description": "How many tags to return in the query output", 500 500 - "required": false, 501 501 - "schema": { 502 502 - "type": "integer", 503 503 - "minimum": 1, 504 504 - "maximum": 100, 505 505 - "default": 25 506 506 - } 507 507 - }, 508 508 - { 509 509 - "name": "actor", 510 510 - "in": "query", 511 511 - "description": "An actor to filter results to", 512 512 - "required": false, 513 513 - "schema": { 514 514 - "type": "string", 515 515 - "description": "An actor to filter results to", 516 516 - "format": "at-identifier" 517 517 - } 518 518 - }, 519 519 - { 520 520 - "name": "cursor", 521 521 - "in": "query", 522 522 - "description": "A parameter to paginate results", 523 523 - "required": false, 524 524 - "schema": { 525 525 - "type": "string", 526 526 - "description": "A parameter to paginate results" 527 527 - } 528 528 - } 529 529 - ], 530 530 - "responses": { 531 531 - "200": { 532 532 - "description": "OK", 533 533 - "content": { 534 534 - "application/json": { 535 535 - "schema": { 536 536 - "type": "object", 537 537 - "properties": { 538 538 - "cursor": { 539 539 - "type": "string", 540 540 - "description": "A parameter to paginate results" 541 541 - }, 542 542 - "tags": { 543 543 - "type": "array", 544 544 - "items": { 545 545 - "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 546 546 - } 547 547 - } 548 548 - } 549 549 - } 550 550 - } 551 551 - } 552 552 - }, 553 553 - "400": { 554 554 - "description": "Bad Request", 555 555 - "content": { 556 556 - "application/json": { 557 557 - "schema": { 558 558 - "type": "object", 559 559 - "properties": { 560 560 - "error": { 561 561 - "type": "string", 562 562 - "description": "A general error code", 563 563 - "oneOf": [ 564 564 - { 565 565 - "const": "InvalidRequest" 566 566 - } 567 567 - ] 568 568 - }, 569 569 - "message": { 570 570 - "type": "string", 571 571 - "description": "A detailed description of the error" 572 572 - } 573 573 - } 574 574 - } 575 575 - } 576 576 - } 577 577 - } 578 578 - } 579 579 - } 580 580 - }, 581 581 - "/xrpc/social.clippr.feed.getClips": { 582 582 - "get": { 583 583 - "tags": [ 584 584 - "Clips" 585 585 - ], 586 586 - "summary": "Get clips", 587 587 - "operationId": "social.clippr.feed.getClips", 588 588 - "description": "Get the hydrated views of a list of clips from their AT URIs.", 589 589 - "parameters": [ 590 590 - { 591 591 - "name": "uris", 592 592 - "in": "query", 593 593 - "description": "List of tag AT-URIs to return hydrated views for", 594 594 - "required": true, 595 595 - "schema": { 596 596 - "type": "array", 597 597 - "items": { 598 598 - "type": "string", 599 599 - "format": "at-uri" 600 600 - }, 601 601 - "maxItems": 25 602 602 - } 603 603 - } 604 604 - ], 605 605 - "responses": { 606 606 - "200": { 607 607 - "description": "OK", 608 608 - "content": { 609 609 - "application/json": { 610 610 - "schema": { 611 611 - "type": "array", 612 612 - "items": { 613 613 - "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 614 614 - } 615 615 - } 616 616 - } 617 617 - } 618 618 - }, 619 619 - "400": { 620 620 - "description": "Bad Request", 621 621 - "content": { 622 622 - "application/json": { 623 623 - "schema": { 624 624 - "type": "object", 625 625 - "properties": { 626 626 - "error": { 627 627 - "type": "string", 628 628 - "description": "A general error code", 629 629 - "oneOf": [ 630 630 - { 631 631 - "const": "InvalidRequest" 632 632 - } 633 633 - ] 634 634 - }, 635 635 - "message": { 636 636 - "type": "string", 637 637 - "description": "A detailed description of the error" 638 638 - } 639 639 - } 640 640 - } 641 641 - } 642 642 - } 643 643 - } 644 644 - } 645 645 - } 646 646 - }, 647 647 - "/xrpc/social.clippr.feed.getTags": { 648 648 - "get": { 649 649 - "tags": [ 650 650 - "Tags" 651 651 - ], 652 652 - "summary": "Get tags", 653 653 - "operationId": "social.clippr.feed.getTags", 654 654 - "description": "Get a the hydrated views of a list of tags from their AT URIs.", 655 655 - "parameters": [ 656 656 - { 657 657 - "name": "uris", 658 658 - "in": "query", 659 659 - "description": "List of tag AT-URIs to return hydrated views for", 660 660 - "required": true, 661 661 - "schema": { 662 662 - "type": "array", 663 663 - "items": { 664 664 - "type": "string", 665 665 - "format": "at-uri" 666 666 - }, 667 667 - "maxItems": 25 668 668 - } 669 669 - } 670 670 - ], 671 671 - "responses": { 672 672 - "200": { 673 673 - "description": "OK", 674 674 - "content": { 675 675 - "application/json": { 676 676 - "schema": { 677 677 - "type": "array", 678 678 - "items": { 679 679 - "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 680 680 - } 681 681 - } 682 682 - } 683 683 - } 684 684 - }, 685 685 - "400": { 686 686 - "description": "Bad Request", 687 687 - "content": { 688 688 - "application/json": { 689 689 - "schema": { 690 690 - "type": "object", 691 691 - "properties": { 692 692 - "error": { 693 693 - "type": "string", 694 694 - "description": "A general error code", 695 695 - "oneOf": [ 696 696 - { 697 697 - "const": "InvalidRequest" 698 698 - } 699 699 - ] 700 700 - }, 701 701 - "message": { 702 702 - "type": "string", 703 703 - "description": "A detailed description of the error" 704 704 - } 705 705 - } 706 706 - } 707 707 - } 708 708 - } 709 709 - } 710 710 - } 711 711 - } 712 712 - }, 713 713 - "/xrpc/social.clippr.feed.getProfileClips": { 714 714 - "get": { 715 715 - "tags": [ 716 716 - "Clips" 717 717 - ], 718 718 - "summary": "Get a profile's clip feed", 719 719 - "operationId": "social.clippr.feed.getProfileClips", 720 720 - "description": "Get a view of a profile's reverse-chronological clips feed.", 721 721 - "parameters": [ 722 722 - { 723 723 - "name": "actor", 724 724 - "in": "query", 725 725 - "description": "An actor to get feed data from", 726 726 - "required": true, 727 727 - "schema": { 728 728 - "type": "string", 729 729 - "description": "An actor to get feed data from", 730 730 - "format": "at-identifier" 731 731 - } 732 732 - }, 733 733 - { 734 734 - "name": "limit", 735 735 - "in": "query", 736 736 - "description": "How many results to return with the query", 737 737 - "required": false, 738 738 - "schema": { 739 739 - "type": "integer", 740 740 - "minimum": 1, 741 741 - "maximum": 100, 742 742 - "default": 50 743 743 - } 744 744 - }, 745 745 - { 746 746 - "name": "cursor", 747 747 - "in": "query", 748 748 - "description": "A parameter to paginate results", 749 749 - "required": false, 750 750 - "schema": { 751 751 - "type": "string", 752 752 - "description": "A parameter to paginate results" 753 753 - } 754 754 - }, 755 755 - { 756 756 - "name": "filter", 757 757 - "in": "query", 758 758 - "description": "What types to include in response", 759 759 - "required": false, 760 760 - "schema": { 761 761 - "type": "string", 762 762 - "description": "What types of clips to include in response", 763 763 - "default": "all_clips", 764 764 - "enum": [ 765 765 - "all_clips", 766 766 - "tagged_clips", 767 767 - "untagged_clips" 768 768 - ] 769 769 - } 770 770 - } 771 771 - ], 772 772 - "responses": { 773 773 - "200": { 774 774 - "description": "OK", 775 775 - "content": { 776 776 - "application/json": { 777 777 - "schema": { 778 778 - "type": "object", 779 779 - "properties": { 780 780 - "cursor": { 781 781 - "type": "string" 782 782 - }, 783 783 - "feed": { 784 784 - "type": "array", 785 785 - "items": { 786 786 - "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 787 787 - } 788 788 - } 789 789 - } 790 790 - } 791 791 - } 792 792 - } 793 793 - }, 794 794 - "400": { 795 795 - "description": "Bad Request", 796 796 - "content": { 797 797 - "application/json": { 798 798 - "schema": { 799 799 - "type": "object", 800 800 - "properties": { 801 801 - "error": { 802 802 - "type": "string", 803 803 - "description": "A general error code", 804 804 - "oneOf": [ 805 805 - { 806 806 - "const": "InvalidRequest" 807 807 - } 808 808 - ] 809 809 - }, 810 810 - "message": { 811 811 - "type": "string", 812 812 - "description": "A detailed description of the error" 813 813 - } 814 814 - } 815 815 - } 816 816 - } 817 817 - } 818 818 - } 819 819 - } 820 820 - } 821 821 - }, 822 822 - "/xrpc/social.clippr.feed.getProfileTags": { 823 823 - "get": { 824 824 - "tags": [ 825 825 - "Tags" 826 826 - ], 827 827 - "summary": "Get a profile's tag feed", 828 828 - "operationId": "social.clippr.feed.getProfileTags", 829 829 - "description": "Get a view of a profile's reverse-chronological clips feed.", 830 830 - "parameters": [ 831 831 - { 832 832 - "name": "actor", 833 833 - "in": "query", 834 834 - "description": "An actor to get feed data from", 835 835 - "required": true, 836 836 - "schema": { 837 837 - "type": "string", 838 838 - "description": "An actor to get feed data from", 839 839 - "format": "at-identifier" 840 840 - } 841 841 - }, 842 842 - { 843 843 - "name": "limit", 844 844 - "in": "query", 845 845 - "description": "How many results to return with the query", 846 846 - "required": false, 847 847 - "schema": { 848 848 - "type": "integer", 849 849 - "minimum": 1, 850 850 - "maximum": 100, 851 851 - "default": 50 852 852 - } 853 853 - }, 854 854 - { 855 855 - "name": "cursor", 856 856 - "in": "query", 857 857 - "description": "A parameter to paginate results", 858 858 - "required": false, 859 859 - "schema": { 860 860 - "type": "string", 861 861 - "description": "A parameter to paginate results" 862 862 - } 863 863 - } 864 864 - ], 865 865 - "responses": { 866 866 - "200": { 867 867 - "description": "OK", 868 868 - "content": { 869 869 - "application/json": { 870 870 - "schema": { 871 871 - "type": "object", 872 872 - "properties": { 873 873 - "cursor": { 874 874 - "type": "string" 875 875 - }, 876 876 - "feed": { 877 877 - "type": "array", 878 878 - "items": { 879 879 - "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 880 880 - } 881 881 - } 882 882 - } 883 883 - } 884 884 - } 885 885 - } 886 886 - }, 887 887 - "400": { 888 888 - "description": "Bad Request", 889 889 - "content": { 890 890 - "application/json": { 891 891 - "schema": { 892 892 - "type": "object", 893 893 - "properties": { 894 894 - "error": { 895 895 - "type": "string", 896 896 - "description": "A general error code", 897 897 - "oneOf": [ 898 898 - { 899 899 - "const": "InvalidRequest" 900 900 - } 901 901 - ] 902 902 - }, 903 903 - "message": { 904 904 - "type": "string", 905 905 - "description": "A detailed description of the error" 906 906 - } 907 907 - } 908 908 - } 909 909 - } 910 910 - } 911 911 - } 912 912 - } 913 913 - } 914 914 - }, 915 915 - "/xrpc/social.clippr.feed.getTagList": { 916 916 - "get": { 917 917 - "tags": [ 918 918 - "Tags" 919 919 - ], 920 920 - "summary": "Get a profile's tag list", 921 921 - "operationId": "social.clippr.feed.getProfileTags", 922 922 - "description": "Get a profile's complete list of tags.", 923 923 - "parameters": [ 924 924 - { 925 925 - "name": "actor", 926 926 - "in": "query", 927 927 - "description": "An actor to fetch the tag list from", 928 928 - "required": false, 929 929 - "schema": { 930 930 - "type": "string", 931 931 - "description": "An actor to fetch the tag list from", 932 932 - "format": "at-identifier" 933 933 - } 934 934 - } 935 935 - ], 936 936 - "responses": { 937 937 - "200": { 938 938 - "description": "OK", 939 939 - "content": { 940 940 - "application/json": { 941 941 - "schema": { 942 942 - "type": "object", 943 943 - "properties": { 944 944 - "tags": { 945 945 - "type": "array", 946 946 - "items": { 947 947 - "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 948 948 - } 949 949 - } 950 950 - } 951 951 - } 952 952 - } 953 953 - } 954 954 - }, 955 955 - "400": { 956 956 - "description": "Bad Request", 957 957 - "content": { 958 958 - "application/json": { 959 959 - "schema": { 960 960 - "type": "object", 961 961 - "properties": { 962 962 - "error": { 963 963 - "type": "string", 964 964 - "description": "A general error code", 965 965 - "oneOf": [ 966 966 - { 967 967 - "error": "InvalidRequest" 968 968 - } 969 969 - ] 970 970 - }, 971 971 - "message": { 972 972 - "type": "string", 973 973 - "description": "A detailed description of the error" 974 974 - } 975 975 - } 976 976 - } 977 977 - } 978 978 - } 979 979 - } 980 980 - } 981 981 - } 982 982 - }, 983 983 - "/xrpc/_health": { 984 984 - "get": { 985 985 - "summary": "Health check", 986 986 - "description": "Check the health of the server. If it is functioning properly, you will receive the server's version number.", 987 987 - "responses": { 988 988 - "200": { 989 989 - "description": "OK", 990 990 - "content": { 991 991 - "application/json": { 992 992 - "schema": { 993 993 - "type": "object", 994 994 - "properties": { 995 995 - "version": { 996 996 - "type": "string", 997 997 - "description": "The version number of the AppView." 998 998 - } 999 999 - } 1000 1000 - } 1001 1001 - } 1002 1002 - } 1003 1003 - } 1004 1004 - }, 1005 1005 - "tags": [ 1006 1006 - "Misc" 1007 1007 - ] 1008 1008 - } 1009 1009 - } 1010 1010 - }, 1011 1011 - "components": { 1012 1012 - "schemas": { 1013 1013 - "com.atproto.repo.strongRef": { 1014 1014 - "type": "object", 1015 1015 - "required": [ 1016 1016 - "uri", 1017 1017 - "cid" 1018 1018 - ], 1019 1019 - "properties": { 1020 1020 - "uri": { 1021 1021 - "type": "string", 1022 1022 - "format": "at-uri" 1023 1023 - }, 1024 1024 - "cid": { 1025 1025 - "type": "string", 1026 1026 - "format": "cid" 1027 1027 - } 1028 1028 - } 1029 1029 - }, 1030 1030 - "social.clippr.actor.defs.profileView": { 1031 1031 - "type": "object", 1032 1032 - "description": "A view of an actor's profile", 1033 1033 - "required": [ 1034 1034 - "did", 1035 1035 - "handle", 1036 1036 - "displayName" 1037 1037 - ], 1038 1038 - "properties": { 1039 1039 - "did": { 1040 1040 - "type": "string", 1041 1041 - "description": "The DID of the profile", 1042 1042 - "format": "did" 1043 1043 - }, 1044 1044 - "handle": { 1045 1045 - "type": "string", 1046 1046 - "description": "The handle of the profile", 1047 1047 - "format": "handle" 1048 1048 - }, 1049 1049 - "displayName": { 1050 1050 - "type": "string", 1051 1051 - "description": "The display name associated to the profile", 1052 1052 - "maxLength": 64 1053 1053 - }, 1054 1054 - "description": { 1055 1055 - "type": "string", 1056 1056 - "description": "The biography associated to the profile", 1057 1057 - "maxLength": 500 1058 1058 - }, 1059 1059 - "avatar": { 1060 1060 - "type": "string", 1061 1061 - "description": "A link to the profile's avatar", 1062 1062 - "format": "uri" 1063 1063 - }, 1064 1064 - "createdAt": { 1065 1065 - "type": "string", 1066 1066 - "description": "When the profile record was first created", 1067 1067 - "format": "date-time" 1068 1068 - } 1069 1069 - } 1070 1070 - }, 1071 1071 - "social.clippr.actor.defs.preferences": { 1072 1072 - "type": "array", 1073 1073 - "items": { 1074 1074 - "oneOf": [ 1075 1075 - { 1076 1076 - "$ref": "#/components/schemas/social.clippr.actor.defs.publishingScopesPref" 1077 1077 - } 1078 1078 - ] 1079 1079 - } 1080 1080 - }, 1081 1081 - "social.clippr.actor.defs.publishingScopesPref": { 1082 1082 - "type": "object", 1083 1083 - "description": "Preferences for a user's publishing scopes", 1084 1084 - "required": [ 1085 1085 - "defaultScope" 1086 1086 - ], 1087 1087 - "properties": { 1088 1088 - "defaultScope": { 1089 1089 - "type": "string", 1090 1090 - "description": "What publishing scope to mark a clip as by default", 1091 1091 - "enum": [ 1092 1092 - "public", 1093 1093 - "unlisted" 1094 1094 - ] 1095 1095 - } 1096 1096 - } 1097 1097 - }, 1098 1098 - "social.clippr.feed.defs.clipView": { 1099 1099 - "type": "object", 1100 1100 - "description": "A view of a single bookmark (or 'clip')", 1101 1101 - "required": [ 1102 1102 - "uri", 1103 1103 - "cid", 1104 1104 - "author", 1105 1105 - "record", 1106 1106 - "indexedAt" 1107 1107 - ], 1108 1108 - "properties": { 1109 1109 - "uri": { 1110 1110 - "type": "string", 1111 1111 - "description": "The AT-URI of the clip", 1112 1112 - "format": "at-uri" 1113 1113 - }, 1114 1114 - "cid": { 1115 1115 - "type": "string", 1116 1116 - "description": "The CID of the clip", 1117 1117 - "format": "cid" 1118 1118 - }, 1119 1119 - "author": { 1120 1120 - "description": "A reference to the actor's profile", 1121 1121 - "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 1122 1122 - }, 1123 1123 - "record": { 1124 1124 - "type": "object", 1125 1125 - "description": "The raw record of the clip" 1126 1126 - }, 1127 1127 - "indexedAt": { 1128 1128 - "type": "string", 1129 1129 - "description": "The time in which the clip's record was indexed by the AppView", 1130 1130 - "format": "date-time" 1131 1131 - } 1132 1132 - } 1133 1133 - }, 1134 1134 - "social.clippr.feed.defs.tagView": { 1135 1135 - "type": "object", 1136 1136 - "description": "A view of a single tag", 1137 1137 - "required": [ 1138 1138 - "uri", 1139 1139 - "cid", 1140 1140 - "author", 1141 1141 - "record", 1142 1142 - "indexedAt" 1143 1143 - ], 1144 1144 - "properties": { 1145 1145 - "uri": { 1146 1146 - "type": "string", 1147 1147 - "description": "The AT-URI to the tag", 1148 1148 - "format": "at-uri" 1149 1149 - }, 1150 1150 - "cid": { 1151 1151 - "type": "string", 1152 1152 - "description": "The CID of the tag", 1153 1153 - "format": "cid" 1154 1154 - }, 1155 1155 - "author": { 1156 1156 - "description": "A reference to the actor's profile", 1157 1157 - "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 1158 1158 - }, 1159 1159 - "record": { 1160 1160 - "type": "object", 1161 1161 - "description": "The raw record of the clip" 1162 1162 - }, 1163 1163 - "indexedAt": { 1164 1164 - "type": "string", 1165 1165 - "description": "The time in which the tag's record was indexed by the AppView", 1166 1166 - "format": "date-time" 1167 1167 - } 1168 1168 - } 1169 1169 - }, 1170 1170 - "social.clippr.actor.profile": { 1171 1171 - "type": "object", 1172 1172 - "required": [ 1173 1173 - "createdAt", 1174 1174 - "displayName" 1175 1175 - ], 1176 1176 - "properties": { 1177 1177 - "displayName": { 1178 1178 - "type": "string", 1179 1179 - "description": "A display name to be shown on a profile", 1180 1180 - "maxLength": 64 1181 1181 - }, 1182 1182 - "description": { 1183 1183 - "type": "string", 1184 1184 - "description": "Text for user to describe themselves", 1185 1185 - "maxLength": 500 1186 1186 - }, 1187 1187 - "avatar": { 1188 1188 - "type": "blob", 1189 1189 - "maxSize": 1000000, 1190 1190 - "description": "Image to show on user's profiles" 1191 1191 - }, 1192 1192 - "createdAt": { 1193 1193 - "type": "string", 1194 1194 - "description": "The creation date of the profile", 1195 1195 - "format": "date-time" 1196 1196 - } 1197 1197 - } 1198 1198 - }, 1199 1199 - "social.clippr.feed.clip": { 1200 1200 - "type": "object", 1201 1201 - "required": [ 1202 1202 - "url", 1203 1203 - "title", 1204 1204 - "description", 1205 1205 - "unlisted", 1206 1206 - "createdAt" 1207 1207 - ], 1208 1208 - "properties": { 1209 1209 - "url": { 1210 1210 - "type": "string", 1211 1211 - "description": "The URL of the bookmark. Cannot be left empty or be modified after creation.", 1212 1212 - "format": "uri", 1213 1213 - "maxLength": 2000 1214 1214 - }, 1215 1215 - "title": { 1216 1216 - "type": "string", 1217 1217 - "description": "The title of the bookmark. If left empty, reuse the URL.", 1218 1218 - "maxLength": 2048 1219 1219 - }, 1220 1220 - "description": { 1221 1221 - "type": "string", 1222 1222 - "description": "A description of the bookmark's content. This should be ripped from the URL metadata and be static for all records using the URL.", 1223 1223 - "maxLength": 4096 1224 1224 - }, 1225 1225 - "notes": { 1226 1226 - "type": "string", 1227 1227 - "description": "User-written notes for the bookmark. Public and personal.", 1228 1228 - "maxLength": 10000 1229 1229 - }, 1230 1230 - "tags": { 1231 1231 - "type": "array", 1232 1232 - "description": "An array of tags. A format of solely alphanumeric characters and dashes should be used.", 1233 1233 - "items": { 1234 1234 - "$ref": "#/components/schemas/com.atproto.repo.strongRef" 1235 1235 - } 1236 1236 - }, 1237 1237 - "unlisted": { 1238 1238 - "type": "boolean", 1239 1239 - "description": "Whether the bookmark can be used for feed indexing and aggregation" 1240 1240 - }, 1241 1241 - "unread": { 1242 1242 - "type": "boolean", 1243 1243 - "description": "Whether the bookmark has been read by the user", 1244 1244 - "default": true 1245 1245 - }, 1246 1246 - "languages": { 1247 1247 - "type": "array", 1248 1248 - "items": { 1249 1249 - "type": "string", 1250 1250 - "format": "language" 1251 1251 - }, 1252 1252 - "maxItems": 5 1253 1253 - }, 1254 1254 - "createdAt": { 1255 1255 - "type": "string", 1256 1256 - "description": "Client-declared timestamp when the bookmark is created", 1257 1257 - "format": "date-time" 1258 1258 - } 1259 1259 - } 1260 1260 - }, 1261 1261 - "social.clippr.feed.tag": { 1262 1262 - "type": "object", 1263 1263 - "required": [ 1264 1264 - "name", 1265 1265 - "createdAt" 1266 1266 - ], 1267 1267 - "properties": { 1268 1268 - "name": { 1269 1269 - "type": "string", 1270 1270 - "description": "A de-duplicated string containing the name of the tag", 1271 1271 - "maxLength": 64 1272 1272 - }, 1273 1273 - "color": { 1274 1274 - "type": "string", 1275 1275 - "description": "A hexadecimal color code", 1276 1276 - "maxLength": 7 1277 1277 - }, 1278 1278 - "description": { 1279 1279 - "type": "string", 1280 1280 - "description": "A description of the tag for additional context", 1281 1281 - "maxLength": 5000 1282 1282 - }, 1283 1283 - "createdAt": { 1284 1284 - "type": "string", 1285 1285 - "description": "A client-defined timestamp for the creation of the tag", 1286 1286 - "format": "date-time" 1287 1287 - } 1288 1288 - } 1289 1289 - } 1290 1290 - } 1291 1291 - } 2 2 + "openapi": "3.1.1", 3 3 + "info": { 4 4 + "title": "Clippr AppView API", 5 5 + "version": "1.0.1", 6 6 + "description": "API reference documentation for Clippr's backend.", 7 7 + "license": { 8 8 + "name": "GNU Affero General Public License v3.0 only", 9 9 + "identifier": "AGPL-3.0-only" 10 10 + } 11 11 + }, 12 12 + "servers": [ 13 13 + { 14 14 + "url": "http://localhost:9090", 15 15 + "description": "Development server" 16 16 + }, 17 17 + { 18 18 + "url": "https://api.clippr.social", 19 19 + "description": "Production server" 20 20 + } 21 21 + ], 22 22 + "tags": [ 23 23 + { 24 24 + "name": "Clips", 25 25 + "description": "API paths that relate to user bookmarks, or 'clips'." 26 26 + }, 27 27 + { 28 28 + "name": "Tags", 29 29 + "description": "API paths that relate to user tags." 30 30 + }, 31 31 + { 32 32 + "name": "Profile", 33 33 + "description": "API paths that relate to user profiles." 34 34 + }, 35 35 + { 36 36 + "name": "Misc", 37 37 + "description": "API paths that don't fit into any other category." 38 38 + } 39 39 + ], 40 40 + "paths": { 41 41 + "/xrpc/social.clippr.actor.getPreferences": { 42 42 + "get": { 43 43 + "tags": ["Profile"], 44 44 + "summary": "Get a user's preferences", 45 45 + "operationId": "social.clippr.actor.getPreferences", 46 46 + "description": "Get a user's private preferences. Requires authentication.", 47 47 + "security": [ 48 48 + { 49 49 + "Bearer": [] 50 50 + } 51 51 + ], 52 52 + "responses": { 53 53 + "200": { 54 54 + "description": "OK", 55 55 + "content": { 56 56 + "application/json": { 57 57 + "schema": { 58 58 + "$ref": "#/components/schemas/social.clippr.actor.defs.preferences" 59 59 + } 60 60 + } 61 61 + } 62 62 + }, 63 63 + "400": { 64 64 + "description": "Bad Request", 65 65 + "content": { 66 66 + "application/json": { 67 67 + "schema": { 68 68 + "type": "object", 69 69 + "properties": { 70 70 + "error": { 71 71 + "type": "string", 72 72 + "description": "A general error code", 73 73 + "oneOf": [ 74 74 + { 75 75 + "const": "InvalidRequest" 76 76 + }, 77 77 + { 78 78 + "const": "ExpiredToken" 79 79 + }, 80 80 + { 81 81 + "const": "InvalidToken" 82 82 + } 83 83 + ] 84 84 + }, 85 85 + "message": { 86 86 + "type": "string", 87 87 + "description": "A detailed description of the error" 88 88 + } 89 89 + } 90 90 + } 91 91 + } 92 92 + } 93 93 + }, 94 94 + "401": { 95 95 + "description": "Unauthorized", 96 96 + "content": { 97 97 + "application/json": { 98 98 + "schema": { 99 99 + "type": "object", 100 100 + "properties": { 101 101 + "error": { 102 102 + "type": "string", 103 103 + "description": "A general error code", 104 104 + "oneOf": [ 105 105 + { 106 106 + "const": "AuthMissing" 107 107 + } 108 108 + ] 109 109 + }, 110 110 + "message": { 111 111 + "type": "string", 112 112 + "description": "A detailed description of the error" 113 113 + } 114 114 + } 115 115 + } 116 116 + } 117 117 + } 118 118 + } 119 119 + } 120 120 + } 121 121 + }, 122 122 + "/xrpc/social.clippr.actor.getProfile": { 123 123 + "get": { 124 124 + "tags": ["Profile"], 125 125 + "summary": "Get a profile", 126 126 + "operationId": "social.clippr.actor.getProfile", 127 127 + "description": "Get a user's profile based on a given DID or handle.", 128 128 + "parameters": [ 129 129 + { 130 130 + "name": "actor", 131 131 + "in": "query", 132 132 + "description": "Handle or DID of account to fetch profile of", 133 133 + "required": true, 134 134 + "content": { 135 135 + "schema": { 136 136 + "type": "string", 137 137 + "description": "Handle or DID of account to fetch profile of", 138 138 + "format": "at-identifier" 139 139 + } 140 140 + }, 141 141 + "deprecated": false, 142 142 + "allowEmptyValue": false 143 143 + } 144 144 + ], 145 145 + "responses": { 146 146 + "200": { 147 147 + "description": "OK", 148 148 + "content": { 149 149 + "application/json": { 150 150 + "schema": { 151 151 + "type": "object", 152 152 + "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 153 153 + } 154 154 + } 155 155 + } 156 156 + }, 157 157 + "400": { 158 158 + "description": "Bad Request", 159 159 + "content": { 160 160 + "application/json": { 161 161 + "schema": { 162 162 + "type": "object", 163 163 + "properties": { 164 164 + "error": { 165 165 + "type": "string", 166 166 + "description": "A general error code", 167 167 + "oneOf": [ 168 168 + { 169 169 + "const": "InvalidRequest" 170 170 + } 171 171 + ] 172 172 + }, 173 173 + "message": { 174 174 + "type": "string", 175 175 + "description": "A detailed description of the error" 176 176 + } 177 177 + } 178 178 + } 179 179 + } 180 180 + } 181 181 + } 182 182 + } 183 183 + } 184 184 + }, 185 185 + "/xrpc/social.clippr.actor.putPreferences": { 186 186 + "post": { 187 187 + "tags": ["Profile"], 188 188 + "summary": "Set a user's preferences", 189 189 + "operationId": "social.clippr.actor.putPreferences", 190 190 + "description": "Sets the private preferences attached to the account. Requires authentication.", 191 191 + "security": [ 192 192 + { 193 193 + "Bearer": [] 194 194 + } 195 195 + ], 196 196 + "requestBody": { 197 197 + "required": true, 198 198 + "content": { 199 199 + "application/json": { 200 200 + "schema": { 201 201 + "type": "object", 202 202 + "properties": { 203 203 + "preferences": { 204 204 + "$ref": "#/components/schemas/social.clippr.actor.defs.preferences" 205 205 + } 206 206 + } 207 207 + } 208 208 + } 209 209 + } 210 210 + }, 211 211 + "responses": { 212 212 + "200": { 213 213 + "description": "OK" 214 214 + }, 215 215 + "400": { 216 216 + "description": "Bad Request", 217 217 + "content": { 218 218 + "application/json": { 219 219 + "schema": { 220 220 + "type": "object", 221 221 + "properties": { 222 222 + "error": { 223 223 + "type": "string", 224 224 + "oneOf": [ 225 225 + { 226 226 + "const": "InvalidRequest" 227 227 + }, 228 228 + { 229 229 + "const": "ExpiredToken" 230 230 + }, 231 231 + { 232 232 + "const": "InvalidToken" 233 233 + } 234 234 + ], 235 235 + "description": "A general error code" 236 236 + }, 237 237 + "message": { 238 238 + "type": "string", 239 239 + "description": "A detailed description of the error" 240 240 + } 241 241 + } 242 242 + } 243 243 + } 244 244 + } 245 245 + }, 246 246 + "401": { 247 247 + "description": "Unauthorized", 248 248 + "content": { 249 249 + "application/json": { 250 250 + "schema": { 251 251 + "type": "object", 252 252 + "properties": { 253 253 + "error": { 254 254 + "type": "string", 255 255 + "description": "A general error code", 256 256 + "oneOf": [ 257 257 + { 258 258 + "const": "AuthMissing" 259 259 + } 260 260 + ] 261 261 + }, 262 262 + "message": { 263 263 + "type": "string", 264 264 + "description": "A detailed description of the error" 265 265 + } 266 266 + } 267 267 + } 268 268 + } 269 269 + } 270 270 + } 271 271 + } 272 272 + } 273 273 + }, 274 274 + "/xrpc/social.clippr.actor.searchClips": { 275 275 + "get": { 276 276 + "tags": ["Clips"], 277 277 + "summary": "Search clips", 278 278 + "operationId": "social.clippr.actor.searchClips", 279 279 + "description": "Find clips matching search criteria.", 280 280 + "parameters": [ 281 281 + { 282 282 + "name": "q", 283 283 + "in": "query", 284 284 + "description": "Search query string", 285 285 + "required": true, 286 286 + "schema": { 287 287 + "type": "string", 288 288 + "description": "Search query string" 289 289 + } 290 290 + }, 291 291 + { 292 292 + "name": "limit", 293 293 + "in": "query", 294 294 + "description": "How many clips to return in the query output", 295 295 + "required": false, 296 296 + "schema": { 297 297 + "type": "integer", 298 298 + "minimum": 1, 299 299 + "maximum": 100, 300 300 + "default": 25 301 301 + } 302 302 + }, 303 303 + { 304 304 + "name": "actor", 305 305 + "in": "query", 306 306 + "description": "An actor to filter results to", 307 307 + "required": false, 308 308 + "schema": { 309 309 + "type": "string", 310 310 + "description": "An actor to filter results to", 311 311 + "format": "at-identifier" 312 312 + } 313 313 + }, 314 314 + { 315 315 + "name": "cursor", 316 316 + "in": "query", 317 317 + "description": "A parameter to paginate results", 318 318 + "required": false, 319 319 + "schema": { 320 320 + "type": "string", 321 321 + "description": "A parameter to paginate results" 322 322 + } 323 323 + } 324 324 + ], 325 325 + "responses": { 326 326 + "200": { 327 327 + "description": "OK", 328 328 + "content": { 329 329 + "application/json": { 330 330 + "schema": { 331 331 + "type": "object", 332 332 + "properties": { 333 333 + "cursor": { 334 334 + "type": "string", 335 335 + "description": "A parameter to paginate results" 336 336 + }, 337 337 + "clips": { 338 338 + "type": "array", 339 339 + "items": { 340 340 + "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 341 341 + } 342 342 + } 343 343 + } 344 344 + } 345 345 + } 346 346 + } 347 347 + }, 348 348 + "400": { 349 349 + "description": "Bad Request", 350 350 + "content": { 351 351 + "application/json": { 352 352 + "schema": { 353 353 + "type": "object", 354 354 + "properties": { 355 355 + "error": { 356 356 + "type": "string", 357 357 + "description": "A general error code", 358 358 + "oneOf": [ 359 359 + { 360 360 + "const": "InvalidRequest" 361 361 + } 362 362 + ] 363 363 + }, 364 364 + "message": { 365 365 + "type": "string", 366 366 + "description": "A detailed description of the error" 367 367 + } 368 368 + } 369 369 + } 370 370 + } 371 371 + } 372 372 + } 373 373 + } 374 374 + } 375 375 + }, 376 376 + "/xrpc/social.clippr.actor.searchProfiles": { 377 377 + "get": { 378 378 + "tags": ["Profile"], 379 379 + "summary": "Search profiles", 380 380 + "operationId": "social.clippr.actor.searchProfiles", 381 381 + "description": "Find profiles matching search criteria.", 382 382 + "parameters": [ 383 383 + { 384 384 + "name": "q", 385 385 + "in": "query", 386 386 + "description": "Search query string", 387 387 + "required": false, 388 388 + "schema": { 389 389 + "type": "string", 390 390 + "description": "Search query string" 391 391 + } 392 392 + }, 393 393 + { 394 394 + "name": "limit", 395 395 + "in": "query", 396 396 + "description": "The number of profiles to be returned in the query", 397 397 + "required": false, 398 398 + "schema": { 399 399 + "type": "integer", 400 400 + "minimum": 1, 401 401 + "maximum": 100, 402 402 + "default": 25 403 403 + } 404 404 + }, 405 405 + { 406 406 + "name": "cursor", 407 407 + "in": "query", 408 408 + "description": "A parameter used for pagination", 409 409 + "required": false, 410 410 + "schema": { 411 411 + "type": "string", 412 412 + "description": "A parameter used for pagination" 413 413 + } 414 414 + } 415 415 + ], 416 416 + "responses": { 417 417 + "200": { 418 418 + "description": "OK", 419 419 + "content": { 420 420 + "application/json": { 421 421 + "schema": { 422 422 + "type": "object", 423 423 + "properties": { 424 424 + "cursor": { 425 425 + "type": "string", 426 426 + "description": "A parameter used for pagination" 427 427 + }, 428 428 + "actors": { 429 429 + "type": "array", 430 430 + "items": { 431 431 + "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 432 432 + } 433 433 + } 434 434 + } 435 435 + } 436 436 + } 437 437 + } 438 438 + }, 439 439 + "400": { 440 440 + "description": "Bad Request", 441 441 + "content": { 442 442 + "application/json": { 443 443 + "schema": { 444 444 + "type": "object", 445 445 + "properties": { 446 446 + "error": { 447 447 + "type": "string", 448 448 + "description": "A general error code", 449 449 + "oneOf": [ 450 450 + { 451 451 + "const": "InvalidRequest" 452 452 + } 453 453 + ] 454 454 + }, 455 455 + "message": { 456 456 + "type": "string", 457 457 + "description": "A detailed description of the error" 458 458 + } 459 459 + } 460 460 + } 461 461 + } 462 462 + } 463 463 + } 464 464 + } 465 465 + } 466 466 + }, 467 467 + "/xrpc/social.clippr.actor.searchTags": { 468 468 + "get": { 469 469 + "tags": ["Tags"], 470 470 + "summary": "Search tags", 471 471 + "operationId": "social.clippr.actor.searchTags", 472 472 + "description": "Find tags matching search criteria.", 473 473 + "parameters": [ 474 474 + { 475 475 + "name": "q", 476 476 + "in": "query", 477 477 + "description": "Search query string", 478 478 + "required": true, 479 479 + "schema": { 480 480 + "type": "string", 481 481 + "description": "Search query string" 482 482 + } 483 483 + }, 484 484 + { 485 485 + "name": "limit", 486 486 + "in": "query", 487 487 + "description": "How many tags to return in the query output", 488 488 + "required": false, 489 489 + "schema": { 490 490 + "type": "integer", 491 491 + "minimum": 1, 492 492 + "maximum": 100, 493 493 + "default": 25 494 494 + } 495 495 + }, 496 496 + { 497 497 + "name": "actor", 498 498 + "in": "query", 499 499 + "description": "An actor to filter results to", 500 500 + "required": false, 501 501 + "schema": { 502 502 + "type": "string", 503 503 + "description": "An actor to filter results to", 504 504 + "format": "at-identifier" 505 505 + } 506 506 + }, 507 507 + { 508 508 + "name": "cursor", 509 509 + "in": "query", 510 510 + "description": "A parameter to paginate results", 511 511 + "required": false, 512 512 + "schema": { 513 513 + "type": "string", 514 514 + "description": "A parameter to paginate results" 515 515 + } 516 516 + } 517 517 + ], 518 518 + "responses": { 519 519 + "200": { 520 520 + "description": "OK", 521 521 + "content": { 522 522 + "application/json": { 523 523 + "schema": { 524 524 + "type": "object", 525 525 + "properties": { 526 526 + "cursor": { 527 527 + "type": "string", 528 528 + "description": "A parameter to paginate results" 529 529 + }, 530 530 + "tags": { 531 531 + "type": "array", 532 532 + "items": { 533 533 + "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 534 534 + } 535 535 + } 536 536 + } 537 537 + } 538 538 + } 539 539 + } 540 540 + }, 541 541 + "400": { 542 542 + "description": "Bad Request", 543 543 + "content": { 544 544 + "application/json": { 545 545 + "schema": { 546 546 + "type": "object", 547 547 + "properties": { 548 548 + "error": { 549 549 + "type": "string", 550 550 + "description": "A general error code", 551 551 + "oneOf": [ 552 552 + { 553 553 + "const": "InvalidRequest" 554 554 + } 555 555 + ] 556 556 + }, 557 557 + "message": { 558 558 + "type": "string", 559 559 + "description": "A detailed description of the error" 560 560 + } 561 561 + } 562 562 + } 563 563 + } 564 564 + } 565 565 + } 566 566 + } 567 567 + } 568 568 + }, 569 569 + "/xrpc/social.clippr.feed.getClips": { 570 570 + "get": { 571 571 + "tags": ["Clips"], 572 572 + "summary": "Get clips", 573 573 + "operationId": "social.clippr.feed.getClips", 574 574 + "description": "Get the hydrated views of a list of clips from their AT URIs.", 575 575 + "parameters": [ 576 576 + { 577 577 + "name": "uris", 578 578 + "in": "query", 579 579 + "description": "List of tag AT-URIs to return hydrated views for", 580 580 + "required": true, 581 581 + "schema": { 582 582 + "type": "array", 583 583 + "items": { 584 584 + "type": "string", 585 585 + "format": "at-uri" 586 586 + }, 587 587 + "maxItems": 25 588 588 + } 589 589 + } 590 590 + ], 591 591 + "responses": { 592 592 + "200": { 593 593 + "description": "OK", 594 594 + "content": { 595 595 + "application/json": { 596 596 + "schema": { 597 597 + "type": "array", 598 598 + "items": { 599 599 + "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 600 600 + } 601 601 + } 602 602 + } 603 603 + } 604 604 + }, 605 605 + "400": { 606 606 + "description": "Bad Request", 607 607 + "content": { 608 608 + "application/json": { 609 609 + "schema": { 610 610 + "type": "object", 611 611 + "properties": { 612 612 + "error": { 613 613 + "type": "string", 614 614 + "description": "A general error code", 615 615 + "oneOf": [ 616 616 + { 617 617 + "const": "InvalidRequest" 618 618 + } 619 619 + ] 620 620 + }, 621 621 + "message": { 622 622 + "type": "string", 623 623 + "description": "A detailed description of the error" 624 624 + } 625 625 + } 626 626 + } 627 627 + } 628 628 + } 629 629 + } 630 630 + } 631 631 + } 632 632 + }, 633 633 + "/xrpc/social.clippr.feed.getTags": { 634 634 + "get": { 635 635 + "tags": ["Tags"], 636 636 + "summary": "Get tags", 637 637 + "operationId": "social.clippr.feed.getTags", 638 638 + "description": "Get a the hydrated views of a list of tags from their AT URIs.", 639 639 + "parameters": [ 640 640 + { 641 641 + "name": "uris", 642 642 + "in": "query", 643 643 + "description": "List of tag AT-URIs to return hydrated views for", 644 644 + "required": true, 645 645 + "schema": { 646 646 + "type": "array", 647 647 + "items": { 648 648 + "type": "string", 649 649 + "format": "at-uri" 650 650 + }, 651 651 + "maxItems": 25 652 652 + } 653 653 + } 654 654 + ], 655 655 + "responses": { 656 656 + "200": { 657 657 + "description": "OK", 658 658 + "content": { 659 659 + "application/json": { 660 660 + "schema": { 661 661 + "type": "array", 662 662 + "items": { 663 663 + "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 664 664 + } 665 665 + } 666 666 + } 667 667 + } 668 668 + }, 669 669 + "400": { 670 670 + "description": "Bad Request", 671 671 + "content": { 672 672 + "application/json": { 673 673 + "schema": { 674 674 + "type": "object", 675 675 + "properties": { 676 676 + "error": { 677 677 + "type": "string", 678 678 + "description": "A general error code", 679 679 + "oneOf": [ 680 680 + { 681 681 + "const": "InvalidRequest" 682 682 + } 683 683 + ] 684 684 + }, 685 685 + "message": { 686 686 + "type": "string", 687 687 + "description": "A detailed description of the error" 688 688 + } 689 689 + } 690 690 + } 691 691 + } 692 692 + } 693 693 + } 694 694 + } 695 695 + } 696 696 + }, 697 697 + "/xrpc/social.clippr.feed.getProfileClips": { 698 698 + "get": { 699 699 + "tags": ["Clips"], 700 700 + "summary": "Get a profile's clip feed", 701 701 + "operationId": "social.clippr.feed.getProfileClips", 702 702 + "description": "Get a view of a profile's reverse-chronological clips feed.", 703 703 + "parameters": [ 704 704 + { 705 705 + "name": "actor", 706 706 + "in": "query", 707 707 + "description": "An actor to get feed data from", 708 708 + "required": true, 709 709 + "schema": { 710 710 + "type": "string", 711 711 + "description": "An actor to get feed data from", 712 712 + "format": "at-identifier" 713 713 + } 714 714 + }, 715 715 + { 716 716 + "name": "limit", 717 717 + "in": "query", 718 718 + "description": "How many results to return with the query", 719 719 + "required": false, 720 720 + "schema": { 721 721 + "type": "integer", 722 722 + "minimum": 1, 723 723 + "maximum": 100, 724 724 + "default": 50 725 725 + } 726 726 + }, 727 727 + { 728 728 + "name": "cursor", 729 729 + "in": "query", 730 730 + "description": "A parameter to paginate results", 731 731 + "required": false, 732 732 + "schema": { 733 733 + "type": "string", 734 734 + "description": "A parameter to paginate results" 735 735 + } 736 736 + }, 737 737 + { 738 738 + "name": "filter", 739 739 + "in": "query", 740 740 + "description": "What types to include in response", 741 741 + "required": false, 742 742 + "schema": { 743 743 + "type": "string", 744 744 + "description": "What types of clips to include in response", 745 745 + "default": "all_clips", 746 746 + "enum": ["all_clips", "tagged_clips", "untagged_clips"] 747 747 + } 748 748 + } 749 749 + ], 750 750 + "responses": { 751 751 + "200": { 752 752 + "description": "OK", 753 753 + "content": { 754 754 + "application/json": { 755 755 + "schema": { 756 756 + "type": "object", 757 757 + "properties": { 758 758 + "cursor": { 759 759 + "type": "string" 760 760 + }, 761 761 + "feed": { 762 762 + "type": "array", 763 763 + "items": { 764 764 + "$ref": "#/components/schemas/social.clippr.feed.defs.clipView" 765 765 + } 766 766 + } 767 767 + } 768 768 + } 769 769 + } 770 770 + } 771 771 + }, 772 772 + "400": { 773 773 + "description": "Bad Request", 774 774 + "content": { 775 775 + "application/json": { 776 776 + "schema": { 777 777 + "type": "object", 778 778 + "properties": { 779 779 + "error": { 780 780 + "type": "string", 781 781 + "description": "A general error code", 782 782 + "oneOf": [ 783 783 + { 784 784 + "const": "InvalidRequest" 785 785 + } 786 786 + ] 787 787 + }, 788 788 + "message": { 789 789 + "type": "string", 790 790 + "description": "A detailed description of the error" 791 791 + } 792 792 + } 793 793 + } 794 794 + } 795 795 + } 796 796 + } 797 797 + } 798 798 + } 799 799 + }, 800 800 + "/xrpc/social.clippr.feed.getProfileTags": { 801 801 + "get": { 802 802 + "tags": ["Tags"], 803 803 + "summary": "Get a profile's tag feed", 804 804 + "operationId": "social.clippr.feed.getProfileTags", 805 805 + "description": "Get a view of a profile's reverse-chronological clips feed.", 806 806 + "parameters": [ 807 807 + { 808 808 + "name": "actor", 809 809 + "in": "query", 810 810 + "description": "An actor to get feed data from", 811 811 + "required": true, 812 812 + "schema": { 813 813 + "type": "string", 814 814 + "description": "An actor to get feed data from", 815 815 + "format": "at-identifier" 816 816 + } 817 817 + }, 818 818 + { 819 819 + "name": "limit", 820 820 + "in": "query", 821 821 + "description": "How many results to return with the query", 822 822 + "required": false, 823 823 + "schema": { 824 824 + "type": "integer", 825 825 + "minimum": 1, 826 826 + "maximum": 100, 827 827 + "default": 50 828 828 + } 829 829 + }, 830 830 + { 831 831 + "name": "cursor", 832 832 + "in": "query", 833 833 + "description": "A parameter to paginate results", 834 834 + "required": false, 835 835 + "schema": { 836 836 + "type": "string", 837 837 + "description": "A parameter to paginate results" 838 838 + } 839 839 + } 840 840 + ], 841 841 + "responses": { 842 842 + "200": { 843 843 + "description": "OK", 844 844 + "content": { 845 845 + "application/json": { 846 846 + "schema": { 847 847 + "type": "object", 848 848 + "properties": { 849 849 + "cursor": { 850 850 + "type": "string" 851 851 + }, 852 852 + "feed": { 853 853 + "type": "array", 854 854 + "items": { 855 855 + "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 856 856 + } 857 857 + } 858 858 + } 859 859 + } 860 860 + } 861 861 + } 862 862 + }, 863 863 + "400": { 864 864 + "description": "Bad Request", 865 865 + "content": { 866 866 + "application/json": { 867 867 + "schema": { 868 868 + "type": "object", 869 869 + "properties": { 870 870 + "error": { 871 871 + "type": "string", 872 872 + "description": "A general error code", 873 873 + "oneOf": [ 874 874 + { 875 875 + "const": "InvalidRequest" 876 876 + } 877 877 + ] 878 878 + }, 879 879 + "message": { 880 880 + "type": "string", 881 881 + "description": "A detailed description of the error" 882 882 + } 883 883 + } 884 884 + } 885 885 + } 886 886 + } 887 887 + } 888 888 + } 889 889 + } 890 890 + }, 891 891 + "/xrpc/social.clippr.feed.getTagList": { 892 892 + "get": { 893 893 + "tags": ["Tags"], 894 894 + "summary": "Get a profile's tag list", 895 895 + "operationId": "social.clippr.feed.getProfileTags", 896 896 + "description": "Get a profile's complete list of tags.", 897 897 + "parameters": [ 898 898 + { 899 899 + "name": "actor", 900 900 + "in": "query", 901 901 + "description": "An actor to fetch the tag list from", 902 902 + "required": false, 903 903 + "schema": { 904 904 + "type": "string", 905 905 + "description": "An actor to fetch the tag list from", 906 906 + "format": "at-identifier" 907 907 + } 908 908 + } 909 909 + ], 910 910 + "responses": { 911 911 + "200": { 912 912 + "description": "OK", 913 913 + "content": { 914 914 + "application/json": { 915 915 + "schema": { 916 916 + "type": "object", 917 917 + "properties": { 918 918 + "tags": { 919 919 + "type": "array", 920 920 + "items": { 921 921 + "$ref": "#/components/schemas/social.clippr.feed.defs.tagView" 922 922 + } 923 923 + } 924 924 + } 925 925 + } 926 926 + } 927 927 + } 928 928 + }, 929 929 + "400": { 930 930 + "description": "Bad Request", 931 931 + "content": { 932 932 + "application/json": { 933 933 + "schema": { 934 934 + "type": "object", 935 935 + "properties": { 936 936 + "error": { 937 937 + "type": "string", 938 938 + "description": "A general error code", 939 939 + "oneOf": [ 940 940 + { 941 941 + "error": "InvalidRequest" 942 942 + } 943 943 + ] 944 944 + }, 945 945 + "message": { 946 946 + "type": "string", 947 947 + "description": "A detailed description of the error" 948 948 + } 949 949 + } 950 950 + } 951 951 + } 952 952 + } 953 953 + } 954 954 + } 955 955 + } 956 956 + }, 957 957 + "/xrpc/_health": { 958 958 + "get": { 959 959 + "summary": "Health check", 960 960 + "description": "Check the health of the server. If it is functioning properly, you will receive the server's version number.", 961 961 + "responses": { 962 962 + "200": { 963 963 + "description": "OK", 964 964 + "content": { 965 965 + "application/json": { 966 966 + "schema": { 967 967 + "type": "object", 968 968 + "properties": { 969 969 + "version": { 970 970 + "type": "string", 971 971 + "description": "The version number of the AppView." 972 972 + } 973 973 + } 974 974 + } 975 975 + } 976 976 + } 977 977 + } 978 978 + }, 979 979 + "tags": ["Misc"] 980 980 + } 981 981 + } 982 982 + }, 983 983 + "components": { 984 984 + "schemas": { 985 985 + "com.atproto.repo.strongRef": { 986 986 + "type": "object", 987 987 + "required": ["uri", "cid"], 988 988 + "properties": { 989 989 + "uri": { 990 990 + "type": "string", 991 991 + "format": "at-uri" 992 992 + }, 993 993 + "cid": { 994 994 + "type": "string", 995 995 + "format": "cid" 996 996 + } 997 997 + } 998 998 + }, 999 999 + "social.clippr.actor.defs.profileView": { 1000 1000 + "type": "object", 1001 1001 + "description": "A view of an actor's profile", 1002 1002 + "required": ["did", "handle", "displayName"], 1003 1003 + "properties": { 1004 1004 + "did": { 1005 1005 + "type": "string", 1006 1006 + "description": "The DID of the profile", 1007 1007 + "format": "did" 1008 1008 + }, 1009 1009 + "handle": { 1010 1010 + "type": "string", 1011 1011 + "description": "The handle of the profile", 1012 1012 + "format": "handle" 1013 1013 + }, 1014 1014 + "displayName": { 1015 1015 + "type": "string", 1016 1016 + "description": "The display name associated to the profile", 1017 1017 + "maxLength": 64 1018 1018 + }, 1019 1019 + "description": { 1020 1020 + "type": "string", 1021 1021 + "description": "The biography associated to the profile", 1022 1022 + "maxLength": 500 1023 1023 + }, 1024 1024 + "avatar": { 1025 1025 + "type": "string", 1026 1026 + "description": "A link to the profile's avatar", 1027 1027 + "format": "uri" 1028 1028 + }, 1029 1029 + "createdAt": { 1030 1030 + "type": "string", 1031 1031 + "description": "When the profile record was first created", 1032 1032 + "format": "date-time" 1033 1033 + } 1034 1034 + } 1035 1035 + }, 1036 1036 + "social.clippr.actor.defs.preferences": { 1037 1037 + "type": "array", 1038 1038 + "items": { 1039 1039 + "oneOf": [ 1040 1040 + { 1041 1041 + "$ref": "#/components/schemas/social.clippr.actor.defs.publishingScopesPref" 1042 1042 + } 1043 1043 + ] 1044 1044 + } 1045 1045 + }, 1046 1046 + "social.clippr.actor.defs.publishingScopesPref": { 1047 1047 + "type": "object", 1048 1048 + "description": "Preferences for a user's publishing scopes", 1049 1049 + "required": ["defaultScope"], 1050 1050 + "properties": { 1051 1051 + "defaultScope": { 1052 1052 + "type": "string", 1053 1053 + "description": "What publishing scope to mark a clip as by default", 1054 1054 + "enum": ["public", "unlisted"] 1055 1055 + } 1056 1056 + } 1057 1057 + }, 1058 1058 + "social.clippr.feed.defs.clipView": { 1059 1059 + "type": "object", 1060 1060 + "description": "A view of a single bookmark (or 'clip')", 1061 1061 + "required": ["uri", "cid", "author", "record", "indexedAt"], 1062 1062 + "properties": { 1063 1063 + "uri": { 1064 1064 + "type": "string", 1065 1065 + "description": "The AT-URI of the clip", 1066 1066 + "format": "at-uri" 1067 1067 + }, 1068 1068 + "cid": { 1069 1069 + "type": "string", 1070 1070 + "description": "The CID of the clip", 1071 1071 + "format": "cid" 1072 1072 + }, 1073 1073 + "author": { 1074 1074 + "description": "A reference to the actor's profile", 1075 1075 + "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 1076 1076 + }, 1077 1077 + "record": { 1078 1078 + "type": "object", 1079 1079 + "description": "The raw record of the clip" 1080 1080 + }, 1081 1081 + "indexedAt": { 1082 1082 + "type": "string", 1083 1083 + "description": "The time in which the clip's record was indexed by the AppView", 1084 1084 + "format": "date-time" 1085 1085 + } 1086 1086 + } 1087 1087 + }, 1088 1088 + "social.clippr.feed.defs.tagView": { 1089 1089 + "type": "object", 1090 1090 + "description": "A view of a single tag", 1091 1091 + "required": ["uri", "cid", "author", "record", "indexedAt"], 1092 1092 + "properties": { 1093 1093 + "uri": { 1094 1094 + "type": "string", 1095 1095 + "description": "The AT-URI to the tag", 1096 1096 + "format": "at-uri" 1097 1097 + }, 1098 1098 + "cid": { 1099 1099 + "type": "string", 1100 1100 + "description": "The CID of the tag", 1101 1101 + "format": "cid" 1102 1102 + }, 1103 1103 + "author": { 1104 1104 + "description": "A reference to the actor's profile", 1105 1105 + "$ref": "#/components/schemas/social.clippr.actor.defs.profileView" 1106 1106 + }, 1107 1107 + "record": { 1108 1108 + "type": "object", 1109 1109 + "description": "The raw record of the clip" 1110 1110 + }, 1111 1111 + "indexedAt": { 1112 1112 + "type": "string", 1113 1113 + "description": "The time in which the tag's record was indexed by the AppView", 1114 1114 + "format": "date-time" 1115 1115 + } 1116 1116 + } 1117 1117 + }, 1118 1118 + "social.clippr.actor.profile": { 1119 1119 + "type": "object", 1120 1120 + "required": ["createdAt", "displayName"], 1121 1121 + "properties": { 1122 1122 + "displayName": { 1123 1123 + "type": "string", 1124 1124 + "description": "A display name to be shown on a profile", 1125 1125 + "maxLength": 64 1126 1126 + }, 1127 1127 + "description": { 1128 1128 + "type": "string", 1129 1129 + "description": "Text for user to describe themselves", 1130 1130 + "maxLength": 500 1131 1131 + }, 1132 1132 + "avatar": { 1133 1133 + "type": "blob", 1134 1134 + "maxSize": 1000000, 1135 1135 + "description": "Image to show on user's profiles" 1136 1136 + }, 1137 1137 + "createdAt": { 1138 1138 + "type": "string", 1139 1139 + "description": "The creation date of the profile", 1140 1140 + "format": "date-time" 1141 1141 + } 1142 1142 + } 1143 1143 + }, 1144 1144 + "social.clippr.feed.clip": { 1145 1145 + "type": "object", 1146 1146 + "required": ["url", "title", "description", "unlisted", "createdAt"], 1147 1147 + "properties": { 1148 1148 + "url": { 1149 1149 + "type": "string", 1150 1150 + "description": "The URL of the bookmark. Cannot be left empty or be modified after creation.", 1151 1151 + "format": "uri", 1152 1152 + "maxLength": 2000 1153 1153 + }, 1154 1154 + "title": { 1155 1155 + "type": "string", 1156 1156 + "description": "The title of the bookmark. If left empty, reuse the URL.", 1157 1157 + "maxLength": 2048 1158 1158 + }, 1159 1159 + "description": { 1160 1160 + "type": "string", 1161 1161 + "description": "A description of the bookmark's content. This should be ripped from the URL metadata and be static for all records using the URL.", 1162 1162 + "maxLength": 4096 1163 1163 + }, 1164 1164 + "notes": { 1165 1165 + "type": "string", 1166 1166 + "description": "User-written notes for the bookmark. Public and personal.", 1167 1167 + "maxLength": 10000 1168 1168 + }, 1169 1169 + "tags": { 1170 1170 + "type": "array", 1171 1171 + "description": "An array of tags. A format of solely alphanumeric characters and dashes should be used.", 1172 1172 + "items": { 1173 1173 + "$ref": "#/components/schemas/com.atproto.repo.strongRef" 1174 1174 + } 1175 1175 + }, 1176 1176 + "unlisted": { 1177 1177 + "type": "boolean", 1178 1178 + "description": "Whether the bookmark can be used for feed indexing and aggregation" 1179 1179 + }, 1180 1180 + "unread": { 1181 1181 + "type": "boolean", 1182 1182 + "description": "Whether the bookmark has been read by the user", 1183 1183 + "default": true 1184 1184 + }, 1185 1185 + "languages": { 1186 1186 + "type": "array", 1187 1187 + "items": { 1188 1188 + "type": "string", 1189 1189 + "format": "language" 1190 1190 + }, 1191 1191 + "maxItems": 5 1192 1192 + }, 1193 1193 + "createdAt": { 1194 1194 + "type": "string", 1195 1195 + "description": "Client-declared timestamp when the bookmark is created", 1196 1196 + "format": "date-time" 1197 1197 + } 1198 1198 + } 1199 1199 + }, 1200 1200 + "social.clippr.feed.tag": { 1201 1201 + "type": "object", 1202 1202 + "required": ["name", "createdAt"], 1203 1203 + "properties": { 1204 1204 + "name": { 1205 1205 + "type": "string", 1206 1206 + "description": "A de-duplicated string containing the name of the tag", 1207 1207 + "maxLength": 64 1208 1208 + }, 1209 1209 + "color": { 1210 1210 + "type": "string", 1211 1211 + "description": "A hexadecimal color code", 1212 1212 + "maxLength": 7 1213 1213 + }, 1214 1214 + "description": { 1215 1215 + "type": "string", 1216 1216 + "description": "A description of the tag for additional context", 1217 1217 + "maxLength": 5000 1218 1218 + }, 1219 1219 + "createdAt": { 1220 1220 + "type": "string", 1221 1221 + "description": "A client-defined timestamp for the creation of the tag", 1222 1222 + "format": "date-time" 1223 1223 + } 1224 1224 + } 1225 1225 + } 1226 1226 + } 1227 1227 + } 1292 1228 }