🐝

JoshBeeTCG
Signup

API endpoints

Public v1 surface for third-party developers. All endpoints require a Bearer token issued from the Developer settings page. Base URL: https://api.joshbeetcg.com

POST /api/v1/edge/detect multipart/form-data #
edge.detect_v1

Bearer token (API key)

Request

Send a single file field containing the card image (PNG or JPEG, max 20MB).

Response

Type: DataResponse<EdgeDetectV1Response>

User-facing response shared by both v1 endpoints (`POST /api/v1/edge/detect` and `POST /api/v1/edge/detect/{id}/rating`). `id` is the row's UUID — pass it to `/rating` to score the detection. `rating` is `None` immediately after detection and populated on the rating response.

type EdgeDetectV1Response = {
  "id": "string",
  "edgePx": "EdgeInnerDistances",
  "ratios": "EdgeInnerRatios",
  "warpedSize": "EdgeWarpedSize",
  "imageUrl": "string",
  "rating": "number | null"
}

Example response

{
  "message": "string",
  "data": {
    "id": "string",
    "edgePx": {
      "top": 0,
      "bottom": 0,
      "left": 0,
      "right": 0
    },
    "ratios": {
      "top": 0,
      "bottom": 0,
      "left": 0,
      "right": 0
    },
    "warpedSize": {
      "width": 0,
      "height": 0
    },
    "imageUrl": "string",
    "rating": 0
  }
}

cURL

curl -X POST "https://api.joshbeetcg.com/api/v1/edge/detect" \
  -H "Authorization: Bearer $JOSHBEE_API_KEY" \
  -F "file=@/path/to/card.jpg"
POST /api/v1/edge/detect/{id}/rating application/json #
edge.rating_v1

Bearer token (API key)

Path parameters

  • id

Request

Body type: EdgeRatingRequest

Request body for `POST /api/v1/edge/detect/{id}/rating`. `rating` must be -1, 0, or 1. The handler enforces the range and produces the user-facing validation error.

type EdgeRatingRequest = {
  "rating": "number"
}

Example body

{
  "rating": 0
}

Response

Type: DataResponse<EdgeDetectV1Response>

User-facing response shared by both v1 endpoints (`POST /api/v1/edge/detect` and `POST /api/v1/edge/detect/{id}/rating`). `id` is the row's UUID — pass it to `/rating` to score the detection. `rating` is `None` immediately after detection and populated on the rating response.

type EdgeDetectV1Response = {
  "id": "string",
  "edgePx": "EdgeInnerDistances",
  "ratios": "EdgeInnerRatios",
  "warpedSize": "EdgeWarpedSize",
  "imageUrl": "string",
  "rating": "number | null"
}

Example response

{
  "message": "string",
  "data": {
    "id": "string",
    "edgePx": {
      "top": 0,
      "bottom": 0,
      "left": 0,
      "right": 0
    },
    "ratios": {
      "top": 0,
      "bottom": 0,
      "left": 0,
      "right": 0
    },
    "warpedSize": {
      "width": 0,
      "height": 0
    },
    "imageUrl": "string",
    "rating": 0
  }
}

cURL

curl -X POST "https://api.joshbeetcg.com/api/v1/edge/detect/{id}/rating" \
  -H "Authorization: Bearer $JOSHBEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 0
  }'

Referenced types

All TypeScript types reachable from the v1 endpoints, generated from the Rust DTOs via ts-rs.

EdgeDetectV1Response

User-facing response shared by both v1 endpoints (`POST /api/v1/edge/detect` and `POST /api/v1/edge/detect/{id}/rating`). `id` is the row's UUID — pass it to `/rating` to score the detection. `rating` is `None` immediately after detection and populated on the rating response.

type EdgeDetectV1Response = {
  "id": "string",
  "edgePx": "EdgeInnerDistances",
  "ratios": "EdgeInnerRatios",
  "warpedSize": "EdgeWarpedSize",
  "imageUrl": "string",
  "rating": "number | null"
}

References: EdgeInnerDistances, EdgeInnerRatios, EdgeWarpedSize

EdgeRatingRequest

Request body for `POST /api/v1/edge/detect/{id}/rating`. `rating` must be -1, 0, or 1. The handler enforces the range and produces the user-facing validation error.

type EdgeRatingRequest = {
  "rating": "number"
}
EdgeInnerDistances

Inner (printed) border widths measured in the warped/flattened card canvas.

type EdgeInnerDistances = {
  "top": "number",
  "bottom": "number",
  "left": "number",
  "right": "number"
}
EdgeInnerRatios

Inner border ratios as percentages (0..100). Top + bottom == 100, left + right == 100. Falls back to 50/50 on degenerate input.

type EdgeInnerRatios = {
  "top": "number",
  "bottom": "number",
  "left": "number",
  "right": "number"
}
EdgeWarpedSize

Warped/flattened canvas dimensions. Used in the v1 response shape.

type EdgeWarpedSize = {
  "width": "number",
  "height": "number"
}