API Reference

Introduction

This API relies on JSON messages.

Token Retrieval

Synopsis

Obtains a short-lived bearer token needed to authorize most requests.

Property Value
HTTP Method POST
Action Path /v2/auth
Authorization API Key credentials given in request body
Request Body JSON
Credits Cost 0

Request Body

{
  "client_id": "<string (required)>",
  "client_secret": "<string (required for client keys)>"
}

For client keys, both client_id and client_secret are required. For widget keys, only client_id is needed.

Successful Response Body

{
  "token_type": "Bearer",
  "access_token": "<string>"
}

Notes

Example

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/auth \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_API_KEY_ID",
    "client_secret": "YOUR_API_SECRET_KEY"
  }'

Response:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiJ9..."
}

Image Recognition

Synopsis

Scans a given image for fish.

Property Value
HTTP Method POST
Action Path /v2/recognize
Authorization Bearer token in Authorization HTTP header
Request Body Binary data (not multipart form data)
Credits Cost 1

Request Body

The request body must be raw binary image data (a sequence of octets). Do not wrap in a multipart form.

Supported image formats:

Not supported: BMP (Windows Bitmap)

The Content-Type header may be set to the image MIME type (e.g. image/jpeg), but application/octet-stream works equally well.

Maximum request body size: 20 MB

Successful Response Body

{
  "ok": true,
  "queryToken": "<string>",
  "objects": [
    {
      "shape": [x1, y1, x2, y2, x3, y3, ...],
      "bbox": [x1, y1, x2, y2],
      "species": [
        {
          "id": "<UUID string>",
          "certainty": 0.0-1.0
        }
      ]
    }
  ],
  "definitions": {
    "<UUID string>": {
      "commonName": "<string>",
      "scientificName": "<string>",
      "imageUrl": "<string>"
    }
  }
}

Field descriptions:

Supported Recognition Options

Recognition options are passed as custom HTTP headers on the /v2/recognize request.

Allowed Characters

Only ASCII alphanumeric characters, spaces, and basic punctuation should be used in header values. Avoid diacritics, CJK scripts, emoji, and line breaks.

Detection Quality Options

Header Description
Fishial-Fish-Detection-Threshold Decimal from 0.3 to 1.0. Lower values detect more fish shapes but increase false positives.
Fishial-Fish-Shape-Max-Points Max points per detected fish shape polygon. Higher = better outline quality; lower = simpler shapes.

Fishial Portal Collection Options

These options only apply when the image is being uploaded to a Fishial Portal collection.

Privacy:

Header Description
Fishial-Face-Obfuscation Blur detected human faces. May partially blur fish if a face is too close.

Image Copyright / Licensing:

Header Description
Fishial-Image-License-Code License code. Values: None, Unknown, Custom, or SPDX codes: CC0-1.0, CC-BY-4.0, CC-BY-NC-4.0, CC-BY-NC-ND-4.0, CC-BY-NC-SA-4.0, CC-BY-ND-4.0, CC-BY-SA-4.0
Fishial-Image-License-Url URL to a license text (relevant with Custom license).
Fishial-Image-License-Author Image author name.
Fishial-Image-License-Source URL or text indicating where the image was obtained.
Fishial-Image-License-Notice Additional copyright information text.

Additional Options:

Header Description
Fishial-Image-Tags Comma-separated list of tags. Example: wow,a,tag → three tags. wow a tag → one tag.
Fishial-Location-Lat-Lon Observation location as latitude, longitude in decimal degrees. Example: -55.260, -67.886

User Feedback

Synopsis

Submit user feedback (opinion) on recognition results.

Property Value
HTTP Method POST
Action Path /v2/feedback
Authorization Bearer token in Authorization header and queryToken in body
Request Body JSON
Credits Cost 0

Request Body

{
  "queryToken": "<string (required)>",
  "objectIndex": "<non-negative integer or null (required)>",
  "opinion": "<string (required)>",
  "suggestedSpeciesName": "<string (optional)>",
  "suggestedSpeciesID": "<UUID string (optional)>"
}

Field descriptions:

Successful Response Body

{
  "ok": true
}

Notes

Submitting multiple feedback entries on a single recognition result is explicitly allowed.

Error Responses

Error responses follow this schema (unless otherwise noted):

{
  "ok": false,
  "error": "<string>",
  "message": "<string>"
}

Caution: Some responses (especially HTTP 5xx server errors) may not adhere to this format or may not be valid JSON.

General Errors

Code Description
auth_token_expired Bearer token has expired. Obtain a new one.
auth_token_invalid Bearer token is invalid for an unspecified reason.
credits_insufficient Not enough API credits to complete the request.

Recognition Errors

Code Description
unsupported_file_format Image file format is not supported. See docs for supported formats.

Feedback Errors

Code Description
feedback_invalid Validation error on feedback submission. Check the error message.
query_token_invalid Query token has expired or is invalid.]( https://github.com/fishial/devapi)