{ "openapi": "3.1.0", "info": { "title": "Catita API", "version": "1.0.0", "description": "Let other bots use Catita in a Discord server. Every key belongs to one server: no endpoint takes a server ID. Guide: https://docs.catita.gg/en/api/" }, "servers": [ { "url": "https://api.catita.gg/v1" } ], "security": [ { "key": [] } ], "paths": { "/me": { "get": { "summary": "The key, its server, scopes and limits", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/levels/leaderboard": { "get": { "summary": "Leaderboard", "x-scope": "levels:read", "description": "Needs the `levels:read` scope.", "parameters": [ { "name": "instance", "in": "query", "schema": { "type": "string", "pattern": "^\\d{1,4}$" }, "description": "Leveling or economy instance. Default: the main one." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string" }, "entries": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "object", "properties": { "rank": { "type": "integer" } } } ] } } } } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/levels/{userId}": { "get": { "summary": "A member's level", "x-scope": "levels:read", "description": "Needs the `levels:read` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{17,20}$" }, "description": "Discord ID of a member of the key's server." }, { "name": "instance", "in": "query", "schema": { "type": "string", "pattern": "^\\d{1,4}$" }, "description": "Leveling or economy instance. Default: the main one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Level" } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/levels/{userId}/xp": { "post": { "summary": "Add or remove XP", "x-scope": "levels:write", "description": "Needs the `levels:write` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{17,20}$" }, "description": "Discord ID of a member of the key's server." }, { "name": "instance", "in": "query", "schema": { "type": "string", "pattern": "^\\d{1,4}$" }, "description": "Leveling or economy instance. Default: the main one." }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "description": "Repeat the same request within 24 h without applying it twice." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": -1000000, "maximum": 1000000, "not": { "const": 0 }, "description": "Positive adds, negative removes." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Level" }, { "type": "object", "properties": { "leveledUp": { "type": "boolean" } } } ] } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cannot be done now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused or unreadable image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/economy/{userId}": { "get": { "summary": "A member's balance", "x-scope": "economy:read", "description": "Needs the `economy:read` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{17,20}$" }, "description": "Discord ID of a member of the key's server." }, { "name": "instance", "in": "query", "schema": { "type": "string", "pattern": "^\\d{1,4}$" }, "description": "Leveling or economy instance. Default: the main one." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/economy/{userId}/wallet": { "post": { "summary": "Give or take wallet money", "x-scope": "economy:write", "description": "Needs the `economy:write` scope.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{17,20}$" }, "description": "Discord ID of a member of the key's server." }, { "name": "instance", "in": "query", "schema": { "type": "string", "pattern": "^\\d{1,4}$" }, "description": "Leveling or economy instance. Default: the main one." }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "description": "Repeat the same request within 24 h without applying it twice." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "type": "integer", "minimum": -1000000000, "maximum": 1000000000, "not": { "const": 0 }, "description": "Positive adds, negative removes." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cannot be done now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused or unreadable image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customroles/keys": { "get": { "summary": "Latest 100 custom role keys", "x-scope": "keys:read", "description": "Needs the `keys:read` scope.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "days": { "type": "integer" }, "claimed": { "type": "boolean" }, "claimedBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create custom role keys (up to 100 a day per API key)", "x-scope": "keys:write", "description": "Needs the `keys:write` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "days" ], "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 365 }, "count": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "days": { "type": "integer" } } } } } } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/fakess": { "post": { "summary": "PNG screenshot of a Discord message (10 a minute)", "x-scope": "fakess", "description": "Needs the `fakess` scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "authorId" ], "properties": { "authorId": { "type": "string", "pattern": "^\\d{17,20}$", "description": "A member of the server: name, avatar and color come from Discord." }, "content": { "type": "string", "maxLength": 2000 }, "reply": { "type": "object", "additionalProperties": false, "required": [ "authorId" ], "properties": { "authorId": { "type": "string", "pattern": "^\\d{17,20}$" }, "content": { "type": "string", "maxLength": 500 } } }, "image": { "type": "string", "format": "uri", "description": "https on cdn.discordapp.com or media.discordapp.net only." }, "theme": { "enum": [ "dark", "darker", "light" ], "default": "dark" } } } } } }, "responses": { "200": { "description": "PNG", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid body or parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope or Catita left the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a member, or unknown instance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused or unreadable image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Busy (see Retry-After)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "level.up": { "post": { "summary": "level.up event", "description": "Signed with Catita-Signature: v1=HMAC-SHA256(secret, `${Catita-Timestamp}.${body}`) in hex.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 5 s acknowledges it." } } } }, "level.rebirth": { "post": { "summary": "level.rebirth event", "description": "Signed with Catita-Signature: v1=HMAC-SHA256(secret, `${Catita-Timestamp}.${body}`) in hex.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 5 s acknowledges it." } } } }, "streak.updated": { "post": { "summary": "streak.updated event", "description": "Signed with Catita-Signature: v1=HMAC-SHA256(secret, `${Catita-Timestamp}.${body}`) in hex.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 5 s acknowledges it." } } } }, "customrole.key_redeemed": { "post": { "summary": "customrole.key_redeemed event", "description": "Signed with Catita-Signature: v1=HMAC-SHA256(secret, `${Catita-Timestamp}.${body}`) in hex.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 5 s acknowledges it." } } } }, "economy.wallet_changed": { "post": { "summary": "economy.wallet_changed event", "description": "Signed with Catita-Signature: v1=HMAC-SHA256(secret, `${Catita-Timestamp}.${body}`) in hex.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 5 s acknowledges it." } } } } }, "components": { "securitySchemes": { "key": { "type": "http", "scheme": "bearer", "description": "ctk_… key from /settings > API." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Me": { "type": "object", "properties": { "guild": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": [ "keys:read", "keys:write", "levels:read", "levels:write", "economy:read", "economy:write", "fakess" ] } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "limits": { "type": "object", "properties": { "perMinute": { "type": "integer" }, "xpPerDay": { "type": "integer" }, "xpLeftToday": { "type": [ "integer", "null" ] }, "moneyPerDay": { "type": "integer" }, "moneyLeftToday": { "type": [ "integer", "null" ] } } } } }, "Level": { "type": "object", "properties": { "userId": { "type": "string" }, "instance": { "type": "string" }, "level": { "type": "integer" }, "xp": { "type": "integer" }, "totalXP": { "type": "integer" }, "rebirths": { "type": "integer" }, "rank": { "type": [ "integer", "null" ] } } }, "Balance": { "type": "object", "properties": { "userId": { "type": "string" }, "instance": { "type": "string" }, "wallet": { "type": "integer" }, "bank": { "type": "integer" }, "bankCapacity": { "type": "integer" }, "netWorth": { "type": "integer" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "enum": [ "level.up", "level.rebirth", "streak.updated", "customrole.key_redeemed", "economy.wallet_changed", "ping" ] }, "guildId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object" } } } } } }