AMPECO Public API Integration Guide

Explore and integrate with the AMPECO EV Charging Platform Public API.

IMPORTANT: Update Reference Docs First

Before using the reference documentation, ensure you have the latest API spec:

bash scripts/fetch-and-generate.sh

This fetches the latest OpenAPI spec from https://developers.ampeco.com/openapi/ and regenerates all reference files.

Prerequisites: curl and jq must be installed:

• macOS: brew install jq
• Ubuntu/Debian: apt-get install jq

Getting Started

1. Get API Access

Contact your AMPECO Customer Success Manager or generate a token in: Back Office → API Access Tokens

2. Base URL

https://{tenantUrl}/public-api/

Replace {tenantUrl} with your organization's tenant URL.

3. Authentication

curl -H "Authorization: Bearer {your-api-token}" \
     https://{tenantUrl}/public-api/resources/charge-points/v2.0/

Quick Reference

Response Format: JSON with data wrapper

{
  "data": [...],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 100, "total": 250 }
}

Path Patterns:

• Resources: /public-api/resources/{resource-name}/v{X.Y}/
• Actions: /public-api/actions/{target}/v{X.Y}/{id}/{action}
• Notifications: /public-api/notifications/v{X.Y}/

Endpoint Quick Index

Run bash scripts/fetch-and-generate.sh to update this index

Actions: See reference/endpoints-index.md for charge point, user, reservation, and notification actions.

Data Model Overview

Understanding how AMPECO entities relate helps you choose the right endpoints.

Operator (tenant scope)
├── Location → ChargePoint → EVSE → Session
├── User → Session, PartnerInvite
├── Partner → ChargePoint (owned), PartnerInvite (users)
└── Tariff, SubscriptionPlan

Common Use Cases:

See reference/data-model.md for detailed relationships and recipes.

Common Patterns

Pagination

Cursor pagination (default, recommended):

GET /public-api/resources/users/v1.0?per_page=25
GET /public-api/resources/users/v1.0?cursor={next_cursor}&per_page=25

Page pagination (legacy support):

GET /public-api/resources/users/v1.0?page=1&per_page=25

Filtering

Use filter[fieldName]=value format:

GET /public-api/resources/sessions/v1.0?filter[userId]=123
GET /public-api/resources/sessions/v1.0?filter[status]=active
GET /public-api/resources/sessions/v1.0?filter[startedAfter]=2024-01-01T00:00:00Z

Includes

Embed related resources with include[]=relationName:

GET /public-api/resources/charge-points/v1.0?include[]=evses&include[]=location

Error Responses

{
  "message": "Unauthenticated."
}

Status codes: 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error)

How to Use This Skill

1. First: Run bash scripts/fetch-and-generate.sh to get latest docs
2. Find endpoints: Load reference/endpoints-index.md
3. Check schemas: Load reference/schemas-index.md
4. Check patterns: Load reference/common-patterns.md for pagination, filtering, errors
5. See deprecated: Load reference/deprecation-map.md

Reference Files

• reference/data-model.md - Entity relationships and use case recipes
• reference/endpoints-index.md - Complete list of all endpoints
• reference/schemas-index.md - Schema summaries
• reference/deprecation-map.md - Deprecated endpoints
• reference/common-patterns.md - Pagination, filtering, errors

Live Documentation

https://developers.ampeco.com