Mismatch API

The Mismatch API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Mismatch API uses API keys to authenticate requests. You can view and manage your API keys in your organization settings.

Getting your API key

1. Navigate to your organization in the Mismatch platform
2. Click the three dots in the top right corner
3. Select Apps
4. Click API key to view or generate your API key

Using your API key

Authentication to the API is performed via HTTP Bearer authentication. Provide your API key as the bearer token value.

curl https://api.mismatch.gr/v1/orgs/{orgId}/events \
  -H "Authorization: Bearer YOUR_API_KEY"

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Base URL

All API requests should be made to:

https://api.mismatch.gr

Response Format

All responses are returned in JSON format. The API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

• 200 OK - The request was successful
• 400 Bad Request - The request was invalid or malformed
• 401 Unauthorized - Authentication failed
• 403 Forbidden - You don’t have permission to access this resource
• 404 Not Found - The requested resource was not found
• 409 Conflict - The request conflicts with the current state of the resource
• 429 Too Many Requests - You have exceeded the rate limit
• 500 Internal Server Error - An error occurred on our servers

Errors

Every error response (any status 400 or above) uses the same JSON envelope, so you can handle failures consistently across all endpoints:

{
  "error": {
    "code": "not_found",
    "message": "Season not found."
  },
  "requestId": "f3a1c9de-2b41-4a0a-9c2e-8d5b6a1f0c44"
}

• error.code - A stable, machine-readable string you can branch on. The value never changes for a given condition (see the table below).
• error.message - A human-readable description of what went wrong. Safe to log, but intended for debugging — branch on error.code, not on this text.
• error.details - Present only for validation errors. An array of { "field", "message" } objects identifying the offending fields.
• requestId - A unique identifier for the request, also returned in the X-Request-Id response header. Include it when contacting support so we can trace the request.

Error Codes

Code	HTTP Status	Meaning
invalid_request	400	The request was malformed or a parameter was invalid.
validation_error	400	One or more fields failed validation. See error.details.
unauthorized	401	Authentication failed — missing, malformed, or invalid API key.
forbidden	403	The API key is valid but not allowed to access this resource.
not_found	404	The requested resource does not exist (or is not visible to your organization).
conflict	409	The request conflicts with the current state of the resource.
rate_limited	429	You have exceeded the rate limit.
internal_error	500	An unexpected error occurred on our servers.

A validation_error includes a details array pinpointing each invalid field:

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": [
      { "field": "seasonId", "message": "Required." }
    ]
  },
  "requestId": "f3a1c9de-2b41-4a0a-9c2e-8d5b6a1f0c44"
}

Rate Limiting

The Mismatch API implements rate limiting to ensure fair usage and maintain service quality. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response with the rate_limited error code.