API Access

API Access#

API Access lets you give a script or AI assistant permission to work with Wildbook through its API. You can create a short-lived token for your own account or use an organization service key for an ongoing integration.

This guide describes Wildbook 11.0. Available features depend on your Wildbook’s version and configuration. If API Access is missing or token creation is disabled, contact your site administrator.

Choose an Access Method#

Use case

Access method

Whose access is used?

Analyze your catalog with a script or AI assistant

Personal token with Read data

Your Wildbook account

Submit new sightings through an enabled submissions pilot

Personal token with Data import

Your enrolled Wildbook account

Run an ongoing organization integration

Organization service key, exchanged for short-lived tokens

The organization’s dedicated service account

A token’s purpose limits what it can do. It does not grant access to records the account cannot otherwise access. A token generated by a site administrator can expose much more data than a researcher’s token, so use an account appropriate for the task.

Create a Personal Token#

  1. Sign in to your Wildbook.

  2. Open your account menu in the navigation bar and select API Access.

  3. Under Token purpose, choose:

    • Read data to search and retrieve data your account can access. This is the default and does not permit imports or catalog edits.

    • Data import to create and import submissions through the separately enabled submissions pilot.

  4. Select Generate API token.

  5. Enter your Wildbook password in Confirm your password, then select Confirm.

  6. Select Copy to copy the token. Note the expiration time shown on the page.

Copy the token before leaving the page; it cannot be retrieved later. When it expires, generate a new one. Its lifetime is configured by your Wildbook administrator, so do not assume a token from one Wildbook lasts as long as a token from another.

Token creation requires a Wildbook password. Accounts that only use single sign-on cannot use this password-confirmation flow.

Read Data With a Script or AI Assistant#

Give your trusted assistant the Wildbook site address, a Read data token, and a description of your task. Do not give it your Wildbook password.

The Copy link button on API Access copies the address of the site’s helper toolbox at /api/v3/agent-skill. The toolbox explains tasks such as finding possible missed matches, reviewing identification problems, and assessing matching quality. These read-only tools suggest changes; you review and apply catalog changes in Wildbook.

For example, ask your assistant:

Read the helper toolbox for my Wildbook and use my read token to look for possible missed matches. Show me the evidence so I can review the suggestions in Wildbook.

Scripts send the token in the HTTP request header:

Authorization: Bearer <your-short-lived-token>

Use the API routes documented by your Wildbook. A token does not replace a browser login or authenticate every legacy Wildbook endpoint. Technical guidance for the read API is available at /api/v3/agent-skill/api-reference on the same site.

Use Data Import Access#

Data import creates a submissions:write token. It requires both:

  • A site administrator to assign the api-submission role to your account.

  • The submissions pilot to be enabled and configured on your Wildbook.

Even site administrators need explicit enrollment. The pilot is disabled by default and supports the default application context, context0, in Wildbook 11.0.

Submissions follow a draft, upload, validate, and commit workflow. New submissions request detection and individual matching by default; an explicit import-only mode skips those steps. Review what will be submitted before committing it.

Read data tokens cannot submit data, and Data import tokens cannot use the general read API. Generate separate tokens if your workflow needs both. A data import token permits submission operations; it does not provide general editing access to existing catalog records.

For the supported fields, request formats, and recovery steps, use /api/v3/agent-skill/submit-sightings on your Wildbook. The machine-readable API contract is at /api/v3/docs/openapi.yaml. Operators enabling the pilot should follow the Wildbook 11.0 submissions runbook.

Protect Your Token#

  • Treat a token like a password. Share it only with the trusted tool that needs it.

  • Use HTTPS and send credentials only to the Wildbook that issued them.

  • Keep tokens out of URLs, source code, screenshots, public issues, and logs.

  • Personal tokens expire automatically. Creating a replacement does not invalidate an earlier token. If one is exposed, stop using it and contact your site administrator.

For integrations that need to renew access without a person generating each token, use organization service keys.

Troubleshooting#

Problem

What to check

Incorrect password or HTTP 401 during token creation

Confirm your Wildbook password. A single sign-on session alone is not sufficient.

Token issuance isn’t enabled on this server or HTTP 503

Ask the site administrator to check the token service configuration.

Data import is refused

Ask the site administrator to check your api-submission role and whether submission admission is enabled.

An API request returns HTTP 401

Check the token’s expiration, the target Wildbook, and the Authorization: Bearer header. Generate a new token if needed.

A read API request fails with a data import token

Generate a separate Read data token. The two purposes are not interchangeable.

Expected records are missing

Check that the token’s account can access those records. Search permissions and indexing can take time to reflect recent changes.