ElePHPant.me API

OpenAPI spec →

Introduction

A free, public JSON API for the PHP community.

Reading is public and needs no API key. Herds marked private by their owner are excluded from every public endpoint. Endpoints that change your own herd or send messages need a token, which you create on your API tokens page while signed in, see Authenticating requests.

The machine-readable spec lives at /docs.openapi. Country codes are ISO 3166-1 alpha-3 (DNK, GBR, BRA).

Be kind to the herd: cache what you fetch rather than re-reading the whole catalogue.

Requests are limited to 120 per minute per IP. Every response contains the X-RateLimit-Limit and X-RateLimit-Remaining.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_API_TOKEN}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Create a token on your API tokens page while signed in, then send it as Authorization: Bearer {token}.

Countries

Which countries have public collectors, and how many.

List countries with public collectors

GET
https://elephpant.me
/api/countries

Returns every country with at least one collector, ordered by collector count descending then name ascending. Use this to discover which country codes are worth passing to /ranking, instead of scraping the ranking page's country selector.

A collector is a public herd holding at least one elePHPant, the same people /ranking lists, so collectors matches the total from /ranking?country={code}. Registered accounts that have not added an elePHPant are not counted and their country does not appear here.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/countries" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 115
access-control-allow-origin: *
{
    "countries": [
        {
            "code": "FRA",
            "code_2": "FR",
            "name": "France",
            "collectors": 122
        },
        {
            "code": "DEU",
            "code_2": "DE",
            "name": "Germany",
            "collectors": 99
        },
        {
            "code": "NLD",
            "code_2": "NL",
            "name": "Netherlands",
            "collectors": 66
        },
        {
            "code": "USA",
            "code_2": "US",
            "name": "United States",
            "collectors": 63
        },
        {
            "code": "GBR",
            "code_2": "GB",
            "name": "United Kingdom",
            "collectors": 40
        },
        {
            "code": "BRA",
            "code_2": "BR",
            "name": "Brazil",
            "collectors": 34
        },
        {
            "code": "POL",
            "code_2": "PL",
            "name": "Poland",
            "collectors": 21
        },
        {
            "code": "BEL",
            "code_2": "BE",
            "name": "Belgium",
            "collectors": 18
        },
        {
            "code": "RUS",
            "code_2": "RU",
            "name": "Russia",
            "collectors": 7
        },
        {
            "code": "AUS",
            "code_2": "AU",
            "name": "Australia",
            "collectors": 6
        },
        {
            "code": "ITA",
            "code_2": "IT",
            "name": "Italy",
            "collectors": 6
        },
        {
            "code": "CAN",
            "code_2": "CA",
            "name": "Canada",
            "collectors": 5
        },
        {
            "code": "ESP",
            "code_2": "ES",
            "name": "Spain",
            "collectors": 5
        },
        {
            "code": "CHE",
            "code_2": "CH",
            "name": "Switzerland",
            "collectors": 5
        },
        {
            "code": "CZE",
            "code_2": "CZ",
            "name": "Czechia",
            "collectors": 4
        },
        {
            "code": "DNK",
            "code_2": "DK",
            "name": "Denmark",
            "collectors": 4
        },
        {
            "code": "GRC",
            "code_2": "GR",
            "name": "Greece",
            "collectors": 4
        },
        {
            "code": "JPN",
            "code_2": "JP",
            "name": "Japan",
            "collectors": 4
        },
        {
            "code": "BLR",
            "code_2": "BY",
            "name": "Belarus",
            "collectors": 3
        },
        {
            "code": "IRL",
            "code_2": "IE",
            "name": "Ireland",
            "collectors": 3
        },
        {
            "code": "ROU",
            "code_2": "RO",
            "name": "Romania",
            "collectors": 3
        },
        {
            "code": "SRB",
            "code_2": "RS",
            "name": "Serbia",
            "collectors": 3
        },
        {
            "code": "SWE",
            "code_2": "SE",
            "name": "Sweden",
            "collectors": 3
        },
        {
            "code": "TWN",
            "code_2": "TW",
            "name": "Taiwan",
            "collectors": 3
        },
        {
            "code": "AFG",
            "code_2": "AF",
            "name": "Afghanistan",
            "collectors": 2
        },
        {
            "code": "AUT",
            "code_2": "AT",
            "name": "Austria",
            "collectors": 2
        },
        {
            "code": "FIN",
            "code_2": "FI",
            "name": "Finland",
            "collectors": 2
        },
        {
            "code": "HUN",
            "code_2": "HU",
            "name": "Hungary",
            "collectors": 2
        },
        {
            "code": "LVA",
            "code_2": "LV",
            "name": "Latvia",
            "collectors": 2
        },
        {
            "code": "LUX",
            "code_2": "LU",
            "name": "Luxembourg",
            "collectors": 2
        },
        {
            "code": "NOR",
            "code_2": "NO",
            "name": "Norway",
            "collectors": 2
        },
        {
            "code": "PAK",
            "code_2": "PK",
            "name": "Pakistan",
            "collectors": 2
        },
        {
            "code": "ZAF",
            "code_2": "ZA",
            "name": "South Africa",
            "collectors": 2
        },
        {
            "code": "LKA",
            "code_2": "LK",
            "name": "Sri Lanka",
            "collectors": 2
        },
        {
            "code": "BGR",
            "code_2": "BG",
            "name": "Bulgaria",
            "collectors": 1
        },
        {
            "code": "CHN",
            "code_2": "CN",
            "name": "China",
            "collectors": 1
        },
        {
            "code": "ECU",
            "code_2": "EC",
            "name": "Ecuador",
            "collectors": 1
        },
        {
            "code": "EUR",
            "code_2": "EU",
            "name": "Europe Union",
            "collectors": 1
        },
        {
            "code": "GHA",
            "code_2": "GH",
            "name": "Ghana",
            "collectors": 1
        },
        {
            "code": "GGY",
            "code_2": "GG",
            "name": "Guernsey",
            "collectors": 1
        },
        {
            "code": "IND",
            "code_2": "IN",
            "name": "India",
            "collectors": 1
        },
        {
            "code": "IDN",
            "code_2": "ID",
            "name": "Indonesia",
            "collectors": 1
        },
        {
            "code": "MEX",
            "code_2": "MX",
            "name": "Mexico",
            "collectors": 1
        },
        {
            "code": "MAR",
            "code_2": "MA",
            "name": "Morocco",
            "collectors": 1
        },
        {
            "code": "NZL",
            "code_2": "NZ",
            "name": "New Zealand",
            "collectors": 1
        },
        {
            "code": "MKD",
            "code_2": "MK",
            "name": "North Macedonia",
            "collectors": 1
        },
        {
            "code": "PNG",
            "code_2": "PG",
            "name": "Papua New Guinea",
            "collectors": 1
        },
        {
            "code": "PER",
            "code_2": "PE",
            "name": "Peru",
            "collectors": 1
        },
        {
            "code": "PRT",
            "code_2": "PT",
            "name": "Portugal",
            "collectors": 1
        },
        {
            "code": "TUR",
            "code_2": "TR",
            "name": "Turkey",
            "collectors": 1
        },
        {
            "code": "UKR",
            "code_2": "UA",
            "name": "Ukraine",
            "collectors": 1
        },
        {
            "code": "VEN",
            "code_2": "VE",
            "name": "Venezuela",
            "collectors": 1
        },
        {
            "code": "VNM",
            "code_2": "VN",
            "name": "Vietnam",
            "collectors": 1
        }
    ]
}
{
    "message": "Server Error"
}

Elephpants

The elePHPant species catalogue and per-species ownership stats.

List all elephpants

GET
https://elephpant.me
/api/elephpants

Returns a paginated catalogue of every elePHPant species, ordered by year then name. Each item includes ownership stats (owners, copies, ownership_percentage) so you can rank rarity without scraping herds.

Defaults to 20 per page; pass per_page up to 100 to pull the whole catalogue in one request. Prefer this when you need to browse or search the species list; use GET /api/elephpants/{id} when you already know the id.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

Page number.

Example:
1
per_page
integer

Species per page, 1 to 100. Defaults to 20

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/elephpants?page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 118
access-control-allow-origin: *
{
    "data": [
        {
            "id": 1,
            "format": "small",
            "name": "Original Blue",
            "description": "First Blue",
            "sponsor": "Nexen / Alter Way",
            "year": 2007,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/1-original-blue.jpg",
            "owners": 211,
            "copies": 340,
            "ownership_percentage": 36.82,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/1"
        },
        {
            "id": 94,
            "format": "large",
            "name": "Original Blue",
            "description": "First Blue",
            "sponsor": "Nexen / Alter Way",
            "year": 2007,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/94-original-blue.jpg",
            "owners": 6,
            "copies": 6,
            "ownership_percentage": 1.05,
            "updated_at": "2026-10-09T12:04:50+00:00",
            "url": "https://elephpant.me/api/elephpants/94"
        },
        {
            "id": 5,
            "format": "small",
            "name": "Oracle",
            "description": "Oracle Blue",
            "sponsor": "Oracle Corporation",
            "year": 2008,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/5-oracle.jpg",
            "owners": 17,
            "copies": 22,
            "ownership_percentage": 2.97,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/5"
        },
        {
            "id": 98,
            "format": "large",
            "name": "Oracle",
            "description": "Oracle Blue",
            "sponsor": "Oracle Corporation",
            "year": 2008,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/98-oracle.jpg",
            "owners": 0,
            "copies": 0,
            "ownership_percentage": 0,
            "updated_at": "2026-10-09T12:04:50+00:00",
            "url": "https://elephpant.me/api/elephpants/98"
        },
        {
            "id": 6,
            "format": "small",
            "name": "Zend Blue",
            "description": "ZendCon 2010",
            "sponsor": "Zend Technologies",
            "year": 2010,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/6-zend-blue.jpg",
            "owners": 29,
            "copies": 33,
            "ownership_percentage": 5.06,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/6"
        },
        {
            "id": 99,
            "format": "large",
            "name": "Zend Blue",
            "description": "ZendCon 2010",
            "sponsor": "Zend Technologies",
            "year": 2010,
            "color": "Blue",
            "image_url": "https://elephpant.me/storage/elephpants/99-zend-blue.jpg",
            "owners": 0,
            "copies": 0,
            "ownership_percentage": 0,
            "updated_at": "2026-10-09T12:04:50+00:00",
            "url": "https://elephpant.me/api/elephpants/99"
        },
        {
            "id": 2,
            "format": "small",
            "name": "Original Pink",
            "description": "First Pink",
            "sponsor": "Alter Way",
            "year": 2011,
            "color": "Pink",
            "image_url": "https://elephpant.me/storage/elephpants/2-original-pink.jpg",
            "owners": 101,
            "copies": 106,
            "ownership_percentage": 17.63,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/2"
        },
        {
            "id": 95,
            "format": "large",
            "name": "Original Pink",
            "description": "First Pink",
            "sponsor": "Alter Way",
            "year": 2011,
            "color": "Pink",
            "image_url": "https://elephpant.me/storage/elephpants/95-original-pink.jpg",
            "owners": 1,
            "copies": 1,
            "ownership_percentage": 0.17,
            "updated_at": "2026-10-09T12:04:50+00:00",
            "url": "https://elephpant.me/api/elephpants/95"
        },
        {
            "id": 13,
            "format": "small",
            "name": "Zend Framework",
            "description": "Zend Green",
            "sponsor": "Zend Technologies",
            "year": 2012,
            "color": "Green",
            "image_url": "https://elephpant.me/storage/elephpants/13-zend-framework.jpg",
            "owners": 51,
            "copies": 55,
            "ownership_percentage": 8.9,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/13"
        },
        {
            "id": 105,
            "format": "large",
            "name": "Zend Framework",
            "description": "Zend Green",
            "sponsor": "Zend Technologies",
            "year": 2012,
            "color": "Green",
            "image_url": "https://elephpant.me/storage/elephpants/105-zend-framework.jpg",
            "owners": 0,
            "copies": 0,
            "ownership_percentage": 0,
            "updated_at": "2026-10-09T12:04:51+00:00",
            "url": "https://elephpant.me/api/elephpants/105"
        },
        {
            "id": 7,
            "format": "small",
            "name": "Chili",
            "description": "Zend Red, ZendCon 2013",
            "sponsor": "Zend Technologies",
            "year": 2013,
            "color": "Red",
            "image_url": "https://elephpant.me/storage/elephpants/7-chili.jpg",
            "owners": 84,
            "copies": 101,
            "ownership_percentage": 14.66,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/7"
        },
        {
            "id": 100,
            "format": "large",
            "name": "Chili",
            "description": "Zend Red, ZendCon 2013",
            "sponsor": "Zend Technologies",
            "year": 2013,
            "color": "Red",
            "image_url": "https://elephpant.me/storage/elephpants/100-chili.jpg",
            "owners": 1,
            "copies": 1,
            "ownership_percentage": 0.17,
            "updated_at": "2026-10-09T12:04:50+00:00",
            "url": "https://elephpant.me/api/elephpants/100"
        },
        {
            "id": 14,
            "format": "small",
            "name": "Archie",
            "description": "php[architect]",
            "sponsor": "php[architect]",
            "year": 2014,
            "color": "Orange",
            "image_url": "https://elephpant.me/storage/elephpants/14-archie.jpg",
            "owners": 143,
            "copies": 161,
            "ownership_percentage": 24.96,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/14"
        },
        {
            "id": 106,
            "format": "large",
            "name": "Archie",
            "description": "php[architect]",
            "sponsor": "php[architect]",
            "year": 2014,
            "color": "Orange",
            "image_url": "https://elephpant.me/storage/elephpants/106-archie.jpg",
            "owners": 2,
            "copies": 2,
            "ownership_percentage": 0.35,
            "updated_at": "2026-10-09T12:04:51+00:00",
            "url": "https://elephpant.me/api/elephpants/106"
        },
        {
            "id": 18,
            "format": "small",
            "name": "Liona",
            "description": "Laravel",
            "sponsor": "Laravel Community",
            "year": 2014,
            "color": "Red",
            "image_url": "https://elephpant.me/storage/elephpants/18-liona.jpg",
            "owners": 168,
            "copies": 200,
            "ownership_percentage": 29.32,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/18"
        },
        {
            "id": 109,
            "format": "large",
            "name": "Liona",
            "description": "Laravel",
            "sponsor": "Laravel Community",
            "year": 2014,
            "color": "Red",
            "image_url": "https://elephpant.me/storage/elephpants/109-liona.jpg",
            "owners": 0,
            "copies": 0,
            "ownership_percentage": 0,
            "updated_at": "2026-10-09T12:04:51+00:00",
            "url": "https://elephpant.me/api/elephpants/109"
        },
        {
            "id": 19,
            "format": "small",
            "name": "MurPHPy",
            "description": "AmsterdamPHP",
            "sponsor": "AmsterdamPHP Community",
            "year": 2014,
            "color": "Black",
            "image_url": "https://elephpant.me/storage/elephpants/19-murphpy.jpg",
            "owners": 124,
            "copies": 149,
            "ownership_percentage": 21.64,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/19"
        },
        {
            "id": 110,
            "format": "large",
            "name": "MurPHPy",
            "description": "AmsterdamPHP",
            "sponsor": "AmsterdamPHP Community",
            "year": 2014,
            "color": "Black",
            "image_url": "https://elephpant.me/storage/elephpants/110-murphpy.jpg",
            "owners": 2,
            "copies": 2,
            "ownership_percentage": 0.35,
            "updated_at": "2026-10-09T12:04:51+00:00",
            "url": "https://elephpant.me/api/elephpants/110"
        },
        {
            "id": 16,
            "format": "small",
            "name": "Sonny",
            "description": "Sunshine PHP Conference",
            "sponsor": "Sunshine PHP, Zend Technologies",
            "year": 2014,
            "color": "Yellow",
            "image_url": "https://elephpant.me/storage/elephpants/16-sonny.jpg",
            "owners": 63,
            "copies": 70,
            "ownership_percentage": 10.99,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/16"
        },
        {
            "id": 15,
            "format": "small",
            "name": "Umoja",
            "description": "PHP Women",
            "sponsor": "PHP Women",
            "year": 2014,
            "color": "Purple",
            "image_url": "https://elephpant.me/storage/elephpants/15-umoja.jpg",
            "owners": 146,
            "copies": 191,
            "ownership_percentage": 25.48,
            "updated_at": "2026-10-09T12:04:47+00:00",
            "url": "https://elephpant.me/api/elephpants/15"
        }
    ],
    "links": {
        "first": "https://elephpant.me/api/elephpants?page=1",
        "last": "https://elephpant.me/api/elephpants?page=7",
        "prev": null,
        "next": "https://elephpant.me/api/elephpants?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 7,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=4",
                "label": "4",
                "page": 4,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=5",
                "label": "5",
                "page": 5,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=6",
                "label": "6",
                "page": 6,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=7",
                "label": "7",
                "page": 7,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/elephpants?page=2",
                "label": "Next »",
                "page": 2,
                "active": false
            }
        ],
        "path": "https://elephpant.me/api/elephpants",
        "per_page": 20,
        "to": 20,
        "total": 124
    }
}
{
    "message": "Server Error"
}

Get a single elePHPant

GET
https://elephpant.me
/api/elephpants/{id}

Returns one species by id, with the same ownership fields as the list endpoint (owners, copies, ownership_percentage) plus catalogue details and image URL.

Use this when you already have an id from the list, a herd, or a ranking payload and only need that species. Returns 404 if the id does not exist.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

id
integer
required

elePHPant ID.

Example:
1
Example request:
curl --request GET \
    --get "https://elephpant.me/api/elephpants/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 117
access-control-allow-origin: *
{
    "data": {
        "id": 1,
        "format": "small",
        "name": "Original Blue",
        "description": "First Blue",
        "sponsor": "Nexen / Alter Way",
        "year": 2007,
        "color": "Blue",
        "image_url": "https://elephpant.me/storage/elephpants/1-original-blue.jpg",
        "owners": 211,
        "copies": 340,
        "ownership_percentage": 36.82,
        "updated_at": "2026-10-09T12:04:47+00:00",
        "url": "https://elephpant.me/api/elephpants/1"
    }
}
{
    "message": "No query results for model [App\\Elephpant]."
}
{
    "message": "Server Error"
}

Herds

A single collector's herd of elePHPants.

Get your own herd

GET
https://elephpant.me
/api/me/herd
requires authentication

Returns the authenticated collector's herd in the same format as the public herd endpoint, also when the herd is private.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request:
curl --request GET \
    --get "https://elephpant.me/api/me/herd" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Unauthenticated."
}
Headers
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
{
    "message": "Unauthenticated."
}

Set a quantity in your herd

PUT
https://elephpant.me
/api/me/herd/{elephpant_id}
requires authentication

Sets how many of an elePHPant the authenticated collector owns. A quantity of 0 removes it from the herd.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

elephpant_id
integer
required

elePHPant ID.

Example:
1

Body Parameters

Example request:
curl --request PUT \
    "https://elephpant.me/api/me/herd/1" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"quantity\": 2
}"
Example response:
[Empty response]
{
    "message": "Unauthenticated."
}

Get a collector's herd

GET
https://elephpant.me
/api/herd/{username}

Returns the full herd of a registered collector, including statistics and collected elePHPants. 403s if the herd is private.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

username
string
required

Collector username.

Example:
john

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/herd/john" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "This herd is private."
}
{
    "message": "No query results for model [App\\User]."
}
Headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 119
access-control-allow-origin: *
{
    "message": "No query results for model [App\\User]."
}
{
    "message": "Server Error"
}

Messages

Your messages with other collectors, such as trade requests.

List your conversations

GET
https://elephpant.me
/api/messages
requires authentication

Returns one entry per collector you have exchanged messages with, newest conversation first, with the latest message.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/messages" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Unauthenticated."
}
Headers
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
{
    "message": "Unauthenticated."
}

Get a conversation

GET
https://elephpant.me
/api/messages/{username}
requires authentication

Returns all messages between you and another collector, oldest first.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

username
string
required

The other collector.

Example:
john

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/messages/john" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Unauthenticated."
}
Headers
cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *
{
    "message": "Unauthenticated."
}
{
    "message": "No query results for model [App\\User]."
}

Send a message

POST
https://elephpant.me
/api/messages/{username}
requires authentication

Sends a message, such as a trade request, to another collector. They also get it by email. Limited to 10 messages per minute.

Headers

Authorization
Example:
Bearer {YOUR_API_TOKEN}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

username
string
required

The collector to message.

Example:
john

Body Parameters

Example request:
curl --request POST \
    "https://elephpant.me/api/messages/john" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"message\": \"Hi! Want to trade spares?\"
}"
Example response:
[Empty response]
{
    "message": "Unauthenticated."
}
{
    "message": "No query results for model [App\\User]."
}

Ranking

Collector leaderboards, globally or scoped to a country.

List the top collectors

GET
https://elephpant.me
/api/ranking

Returns public herds ranked by number of unique elePHPants, then by total elePHPants, then alphabetically by name. rank is the position in the full ordering (not page-relative), and updated_at is an exact timestamp, not a rendered relative string, so it stays accurate however long you hold onto the response.

Headers

Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

country
string

ISO 3166-1 alpha-3 country code to filter the ranking by.

Example:
GBR
page
integer

Page number.

Example:
1

Response Fields

Example request:
curl --request GET \
    --get "https://elephpant.me/api/ranking?country=GBR&page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
Headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 116
access-control-allow-origin: *
{
    "data": [
        {
            "rank": 1,
            "username": "derickr",
            "name": "Derick",
            "country": "GBR",
            "stats": {
                "total": 80,
                "unique": 78,
                "spare": 2
            },
            "updated_at": "2026-10-27T20:42:46+00:00",
            "herd_url": "https://elephpant.me/herd/derickr"
        },
        {
            "rank": 2,
            "username": "giveupalready",
            "name": "Chris Riley",
            "country": "GBR",
            "stats": {
                "total": 364,
                "unique": 58,
                "spare": 306
            },
            "updated_at": "2026-10-15T23:27:48+00:00",
            "herd_url": "https://elephpant.me/herd/giveupalready"
        },
        {
            "rank": 3,
            "username": "jonpurvis_",
            "name": "Jon Purvis",
            "country": "GBR",
            "stats": {
                "total": 73,
                "unique": 58,
                "spare": 15
            },
            "updated_at": "2026-10-08T22:58:41+00:00",
            "herd_url": "https://elephpant.me/herd/jonpurvis_"
        },
        {
            "rank": 4,
            "username": "Brunty",
            "name": "Brunty",
            "country": "GBR",
            "stats": {
                "total": 57,
                "unique": 43,
                "spare": 14
            },
            "updated_at": "2026-03-08T11:49:50+00:00",
            "herd_url": "https://elephpant.me/herd/Brunty"
        },
        {
            "rank": 5,
            "username": "akrabat",
            "name": "Rob Allen",
            "country": "GBR",
            "stats": {
                "total": 45,
                "unique": 36,
                "spare": 9
            },
            "updated_at": "2026-02-08T16:51:10+00:00",
            "herd_url": "https://elephpant.me/herd/akrabat"
        },
        {
            "rank": 6,
            "username": "nerdydeveloper",
            "name": "James Wilson",
            "country": "GBR",
            "stats": {
                "total": 56,
                "unique": 32,
                "spare": 24
            },
            "updated_at": "2022-06-23T07:46:07+00:00",
            "herd_url": "https://elephpant.me/herd/nerdydeveloper"
        },
        {
            "rank": 7,
            "username": "LiamHammett",
            "name": "Liam Hammett",
            "country": "GBR",
            "stats": {
                "total": 23,
                "unique": 22,
                "spare": 1
            },
            "updated_at": "2026-09-10T12:13:04+00:00",
            "herd_url": "https://elephpant.me/herd/LiamHammett"
        },
        {
            "rank": 8,
            "username": "cemerson",
            "name": "Chris Emerson",
            "country": "GBR",
            "stats": {
                "total": 24,
                "unique": 20,
                "spare": 4
            },
            "updated_at": "2023-12-22T11:29:55+00:00",
            "herd_url": "https://elephpant.me/herd/cemerson"
        },
        {
            "rank": 9,
            "username": "gbuckingham89",
            "name": "George Buckingham",
            "country": "GBR",
            "stats": {
                "total": 22,
                "unique": 20,
                "spare": 2
            },
            "updated_at": "2025-07-24T12:00:20+00:00",
            "herd_url": "https://elephpant.me/herd/gbuckingham89"
        },
        {
            "rank": 10,
            "username": "girgias",
            "name": "Gina P. Banyard",
            "country": "GBR",
            "stats": {
                "total": 22,
                "unique": 19,
                "spare": 3
            },
            "updated_at": "2025-05-22T22:05:54+00:00",
            "herd_url": "https://elephpant.me/herd/girgias"
        },
        {
            "rank": 11,
            "username": "kasper_franz",
            "name": "Kasper Sanguesa-Franz",
            "country": "GBR",
            "stats": {
                "total": 21,
                "unique": 18,
                "spare": 3
            },
            "updated_at": "2022-07-14T06:56:17+00:00",
            "herd_url": "https://elephpant.me/herd/kasper_franz"
        },
        {
            "rank": 12,
            "username": "tdc_hodgy",
            "name": "James Hodgson",
            "country": "GBR",
            "stats": {
                "total": 16,
                "unique": 16,
                "spare": 0
            },
            "updated_at": "2021-08-01T09:49:55+00:00",
            "herd_url": "https://elephpant.me/herd/tdc_hodgy"
        },
        {
            "rank": 13,
            "username": "SecondeJ",
            "name": "Jim Seconde",
            "country": "GBR",
            "stats": {
                "total": 16,
                "unique": 16,
                "spare": 0
            },
            "updated_at": "2023-10-25T19:28:48+00:00",
            "herd_url": "https://elephpant.me/herd/SecondeJ"
        },
        {
            "rank": 14,
            "username": "pieceofthepie",
            "name": "Adam Buntain-Cooper",
            "country": "GBR",
            "stats": {
                "total": 13,
                "unique": 13,
                "spare": 0
            },
            "updated_at": "2024-10-14T10:02:03+00:00",
            "herd_url": "https://elephpant.me/herd/pieceofthepie"
        },
        {
            "rank": 15,
            "username": "MintopiaUK",
            "name": "Jessica Smith",
            "country": "GBR",
            "stats": {
                "total": 12,
                "unique": 12,
                "spare": 0
            },
            "updated_at": "2023-06-09T14:25:04+00:00",
            "herd_url": "https://elephpant.me/herd/MintopiaUK"
        },
        {
            "rank": 16,
            "username": "AranReeks",
            "name": "Aran",
            "country": "GBR",
            "stats": {
                "total": 10,
                "unique": 10,
                "spare": 0
            },
            "updated_at": "2020-08-30T08:47:41+00:00",
            "herd_url": "https://elephpant.me/herd/AranReeks"
        },
        {
            "rank": 17,
            "username": "JustSteveKing",
            "name": "Steve McDougall",
            "country": "GBR",
            "stats": {
                "total": 9,
                "unique": 9,
                "spare": 0
            },
            "updated_at": "2021-06-18T17:04:36+00:00",
            "herd_url": "https://elephpant.me/herd/JustSteveKing"
        },
        {
            "rank": 18,
            "username": "chris-normansell",
            "name": "Chris Normansell",
            "country": "GBR",
            "stats": {
                "total": 9,
                "unique": 8,
                "spare": 1
            },
            "updated_at": "2020-06-14T10:15:16+00:00",
            "herd_url": "https://elephpant.me/herd/chris-normansell"
        },
        {
            "rank": 19,
            "username": "grantbennett",
            "name": "Grant Bennett",
            "country": "GBR",
            "stats": {
                "total": 9,
                "unique": 8,
                "spare": 1
            },
            "updated_at": "2023-07-18T22:26:33+00:00",
            "herd_url": "https://elephpant.me/herd/grantbennett"
        },
        {
            "rank": 20,
            "username": "phpyorkshire",
            "name": "PHP Yorkshire",
            "country": "GBR",
            "stats": {
                "total": 256,
                "unique": 7,
                "spare": 249
            },
            "updated_at": "2020-10-29T22:21:57+00:00",
            "herd_url": "https://elephpant.me/herd/phpyorkshire"
        },
        {
            "rank": 21,
            "username": "stephen-russell",
            "name": "Stephen Russell",
            "country": "GBR",
            "stats": {
                "total": 12,
                "unique": 7,
                "spare": 5
            },
            "updated_at": "2023-10-25T19:35:38+00:00",
            "herd_url": "https://elephpant.me/herd/stephen-russell"
        },
        {
            "rank": 22,
            "username": "opdavies",
            "name": "Oliver Davies",
            "country": "GBR",
            "stats": {
                "total": 7,
                "unique": 7,
                "spare": 0
            },
            "updated_at": "2020-07-02T17:44:44+00:00",
            "herd_url": "https://elephpant.me/herd/opdavies"
        },
        {
            "rank": 23,
            "username": "TheGingerDog",
            "name": "David Goodwin",
            "country": "GBR",
            "stats": {
                "total": 11,
                "unique": 6,
                "spare": 5
            },
            "updated_at": "2025-02-22T10:44:02+00:00",
            "herd_url": "https://elephpant.me/herd/TheGingerDog"
        },
        {
            "rank": 24,
            "username": "asgrim",
            "name": "Asgrim",
            "country": "GBR",
            "stats": {
                "total": 6,
                "unique": 6,
                "spare": 0
            },
            "updated_at": "2023-08-09T09:04:11+00:00",
            "herd_url": "https://elephpant.me/herd/asgrim"
        },
        {
            "rank": 25,
            "username": "dom-mclaughlin",
            "name": "Dom McLaughlin",
            "country": "GBR",
            "stats": {
                "total": 6,
                "unique": 6,
                "spare": 0
            },
            "updated_at": "2026-06-01T19:47:20+00:00",
            "herd_url": "https://elephpant.me/herd/dom-mclaughlin"
        },
        {
            "rank": 26,
            "username": "dcblogdev",
            "name": "David Carr",
            "country": "GBR",
            "stats": {
                "total": 6,
                "unique": 4,
                "spare": 2
            },
            "updated_at": "2024-04-18T09:43:47+00:00",
            "herd_url": "https://elephpant.me/herd/dcblogdev"
        },
        {
            "rank": 27,
            "username": "ethan",
            "name": "Ethan",
            "country": "GBR",
            "stats": {
                "total": 4,
                "unique": 4,
                "spare": 0
            },
            "updated_at": "2021-05-22T11:47:00+00:00",
            "herd_url": "https://elephpant.me/herd/ethan"
        },
        {
            "rank": 28,
            "username": "carlcasbolt",
            "name": "Carl Casbolt",
            "country": "GBR",
            "stats": {
                "total": 3,
                "unique": 3,
                "spare": 0
            },
            "updated_at": "2025-02-12T14:10:04+00:00",
            "herd_url": "https://elephpant.me/herd/carlcasbolt"
        },
        {
            "rank": 29,
            "username": "ccmiller2018",
            "name": "Christopher Miller",
            "country": "GBR",
            "stats": {
                "total": 3,
                "unique": 3,
                "spare": 0
            },
            "updated_at": "2025-02-17T20:32:46+00:00",
            "herd_url": "https://elephpant.me/herd/ccmiller2018"
        },
        {
            "rank": 30,
            "username": "fusedreality",
            "name": "Craig McCreath",
            "country": "GBR",
            "stats": {
                "total": 3,
                "unique": 3,
                "spare": 0
            },
            "updated_at": "2019-11-13T15:08:42+00:00",
            "herd_url": "https://elephpant.me/herd/fusedreality"
        },
        {
            "rank": 31,
            "username": "tillythecoder",
            "name": "Tilly The Coder",
            "country": "GBR",
            "stats": {
                "total": 3,
                "unique": 3,
                "spare": 0
            },
            "updated_at": "2026-06-26T13:23:49+00:00",
            "herd_url": "https://elephpant.me/herd/tillythecoder"
        },
        {
            "rank": 32,
            "username": "LucyWynneJones1",
            "name": "Lucy Wynne-Jones",
            "country": "GBR",
            "stats": {
                "total": 3,
                "unique": 2,
                "spare": 1
            },
            "updated_at": "2022-09-29T12:59:43+00:00",
            "herd_url": "https://elephpant.me/herd/LucyWynneJones1"
        },
        {
            "rank": 33,
            "username": "garygabbles",
            "name": "Gary Fuller",
            "country": "GBR",
            "stats": {
                "total": 2,
                "unique": 2,
                "spare": 0
            },
            "updated_at": "2025-02-20T16:45:56+00:00",
            "herd_url": "https://elephpant.me/herd/garygabbles"
        },
        {
            "rank": 34,
            "username": "jxckaroo",
            "name": "Jack Mollart",
            "country": "GBR",
            "stats": {
                "total": 2,
                "unique": 2,
                "spare": 0
            },
            "updated_at": "2022-07-06T09:02:10+00:00",
            "herd_url": "https://elephpant.me/herd/jxckaroo"
        },
        {
            "rank": 35,
            "username": "kanitrobinson",
            "name": "Kani Robinson",
            "country": "GBR",
            "stats": {
                "total": 6,
                "unique": 1,
                "spare": 5
            },
            "updated_at": "2020-07-03T15:16:36+00:00",
            "herd_url": "https://elephpant.me/herd/kanitrobinson"
        },
        {
            "rank": 36,
            "username": "brunosabenca",
            "name": "Bruno",
            "country": "GBR",
            "stats": {
                "total": 1,
                "unique": 1,
                "spare": 0
            },
            "updated_at": "2026-02-21T12:14:17+00:00",
            "herd_url": "https://elephpant.me/herd/brunosabenca"
        },
        {
            "rank": 37,
            "username": "colin-mccrory",
            "name": "Colin McCrory",
            "country": "GBR",
            "stats": {
                "total": 1,
                "unique": 1,
                "spare": 0
            },
            "updated_at": "2021-06-21T10:33:49+00:00",
            "herd_url": "https://elephpant.me/herd/colin-mccrory"
        },
        {
            "rank": 38,
            "username": "julie-kennard",
            "name": "Julie Kennard",
            "country": "GBR",
            "stats": {
                "total": 1,
                "unique": 1,
                "spare": 0
            },
            "updated_at": "2021-02-19T11:41:00+00:00",
            "herd_url": "https://elephpant.me/herd/julie-kennard"
        },
        {
            "rank": 39,
            "username": "simon-bennett",
            "name": "Simon Bennett",
            "country": "GBR",
            "stats": {
                "total": 1,
                "unique": 1,
                "spare": 0
            },
            "updated_at": "2026-06-25T15:11:30+00:00",
            "herd_url": "https://elephpant.me/herd/simon-bennett"
        },
        {
            "rank": 40,
            "username": "william-david-murray",
            "name": "William David Murray",
            "country": "GBR",
            "stats": {
                "total": 1,
                "unique": 1,
                "spare": 0
            },
            "updated_at": "2025-11-26T20:24:35+00:00",
            "herd_url": "https://elephpant.me/herd/william-david-murray"
        }
    ],
    "links": {
        "first": "https://elephpant.me/api/ranking?page=1",
        "last": "https://elephpant.me/api/ranking?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://elephpant.me/api/ranking?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "https://elephpant.me/api/ranking",
        "per_page": 50,
        "to": 40,
        "total": 40
    }
}
{
    "message": "Server Error"
}