FC Barcelona API Documentation Guide — Everything You Need in 2026

Understanding the Barça API Documentation

The Barça API comes with two ways to explore the documentation: interactive API docs powered by Scalar, and an in-browser terminal for quick exploration. This guide walks you through both.

The Interactive API Docs

Visit /docs to access the full OpenAPI documentation. It is powered by Scalar — a modern API docs viewer that lets you:

• Browse every endpoint with its full parameter list
• See example request and response objects
• Send test requests directly from the browser (no tools needed)
• Understand error responses and status codes

Navigating the Docs

The sidebar lists all available endpoints grouped by category. Click any endpoint to expand its details:

Request parameters — query params like position for the squad endpoint, path params like :id for the player endpoint.

Response schema — the full shape of the JSON response, with field names and types.

Example response — a realistic sample of what the API actually returns.

Making a Test Request from the Docs

1. Open /docs
2. Click the /api/squad endpoint
3. Click "Try it" (or equivalent in Scalar)
4. Optionally add position=FW as a query parameter
5. Click Send — you will see the live response from the real API

No API key, no setup. The docs connect to the live API.

The Interactive Terminal

For a more hands-on experience, the terminal lets you query the API through a command-line interface in the browser.

Available Commands

/help              — Show all available commands
/squad             — Get full squad
/squad FW          — Filter forwards
/squad GK          — Filter goalkeepers
/squad DF          — Filter defenders
/squad MF          — Filter midfielders
/player <number>   — Get player by shirt number
/next-match        — Get next scheduled match
/calendar          — Get match calendar
/standings         — Get La Liga standings
/scorers           — Top scorers (LAL or UCL)
/h2h <team>        — Head-to-head vs opponent
/about             — About this project
/lang en           — Switch to English
/lang pt-br        — Switch to Portuguese
/lang es           — Switch to Spanish
/clear             — Clear terminal output

Terminal vs. API Docs

	Terminal	API Docs
Best for	Quick exploration	Understanding full API
Shows raw JSON	Formatted output	Full JSON schema
Test parameters	Command arguments	Interactive form
Reference material	No	Yes

Use the terminal to quickly check "what does the squad data look like?" and the docs to understand "what are all the fields and what do they mean?"

Request Format Reference

All Barça API endpoints are:

• HTTP Method: GET only
• Base URL: https://api.fc-barcelona.app
• Response format: JSON with a data field
• Authentication: None required
• CORS: Enabled for all origins

Standard Response Envelope

All successful responses follow this structure:

{
  "data": { ... },
  "meta": {
    "cached_at": "2026-03-21T12:00:00.000Z",
    "cache_expires_at": "2026-03-22T12:00:00.000Z"
  }
}

Error Responses

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Player not found"
  }
}

HTTP status codes are used correctly: 200 for success, 400 for validation errors, 404 for not found, 429 for rate limit exceeded.

Rate Limits

The API implements fair-use rate limiting. For personal projects and demos, you will not hit these limits under normal usage. If you need to make many requests in a short time (bulk data import, etc.), add delays between requests.

Code Examples by Language

JavaScript / TypeScript

const response = await fetch('https://api.fc-barcelona.app/api/squad');
const { data } = await response.json();

Python

import requests
response = requests.get('https://api.fc-barcelona.app/api/squad')
data = response.json()['data']

cURL

curl -s https://api.fc-barcelona.app/api/squad | jq '.data[0]'

Start Exploring

Open the interactive docs or launch the terminal — both are free, require no setup, and connect to the live API.