API Reference

The CaneToad API provides RESTful access to Australian mining and geological data.

Base URL

https://api.canetoad.ai/api/v1

Authentication

All requests require authentication via API token. Include your token in the Authorization header:

Authorization: Bearer ct_your_token

Or as a query parameter (for spreadsheets):

?api_key=ct_your_token

Response Format

All responses return JSON by default:

{
  "data": [...],
  "meta": {
    "total": 1500,
    "page": 1,
    "per_page": 50,
    "total_pages": 30
  }
}

Use ?format=csv or ?format=tsv for spreadsheet-compatible output.

Available Endpoints

Companies

GET /companies

List ASX-listed mining companies

GET /companies/:code

Get a specific company by ASX code

GET /companies/:code/tenements

List tenements for a company

GET /companies/:code/subsidiaries

List subsidiaries for a company

Tenements

GET /tenements

List mining tenements

GET /tenements/:id

Get a specific tenement

Reports

GET /reports

List company announcements

GET /reports/:hash

Get a specific report

Companies

List Companies

GET /companies

Get a paginated list of ASX-listed resource companies.

Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max 100)
`search`	string	-	Search by name or ASX code
`sector`	string	-	Filter by GICS sector
`active`	boolean	true	Filter by active status
`sort`	string	name	Sort by: name, market_cap, asx_code
`order`	string	asc	Sort order: asc, desc
`format`	string	json	Output format: json, csv, tsv

Example Request:

curl -H "Authorization: Bearer ct_your_token" \
  "https://api.canetoad.ai/api/v1/companies?sector=Materials&per_page=10"

Example Response:

{
  "data": [
    {
      "asx_code": "BHP",
      "company_name": "BHP Group Limited",
      "market_cap_aud": 150000000000,
      "gics_sector": "Materials",
      "gics_industry_group": "Materials",
      "total_tenements": 250,
      "is_active": true
    }
  ],
  "meta": {
    "total": 500,
    "page": 1,
    "per_page": 10,
    "total_pages": 50
  }
}

Get Company by Code

GET /companies/:code

Get a specific company by ASX code.

Path Parameters:

Parameter	Type	Description
`code`	string	ASX code (e.g., "BHP")

Example Request:

curl -H "Authorization: Bearer ct_your_token" \
  "https://api.canetoad.ai/api/v1/companies/BHP"

Example Response:

{
  "data": {
    "asx_code": "BHP",
    "company_name": "BHP Group Limited",
    "market_cap_aud": 150000000000,
    "gics_sector": "Materials",
    "gics_industry_group": "Materials",
    "total_tenements": 250,
    "is_active": true
  }
}

List Company Tenements

GET /companies/:code/tenements

List tenements for a specific company.

Path Parameters:

Parameter	Type	Description
`code`	string	ASX code (e.g., "BHP")

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max 100)
`state`	string	-	Filter by state (WA, NSW, etc.)
`status`	string	-	Filter by tenement status

List Company Subsidiaries

GET /companies/:code/subsidiaries

List subsidiaries for a specific company.

Path Parameters:

Parameter	Type	Description
`code`	string	ASX code (e.g., "BHP")

Tenements

List Tenements

GET /tenements

Get a paginated list of mining tenements.

Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max 100)
`state`	string	-	Filter by state (WA, NSW, QLD, etc.)
`status`	string	-	Filter by status (granted, pending, etc.)
`type`	string	-	Filter by tenement type
`holder`	string	-	Search by holder name
`format`	string	json	Output format: json, csv, tsv

Example Request:

curl -H "Authorization: Bearer ct_your_token" \
  "https://api.canetoad.ai/api/v1/tenements?state=WA&per_page=10"

Get Tenement by ID

GET /tenements/:id

Get a specific tenement by ID.

Path Parameters:

Parameter	Type	Description
`id`	string	Tenement ID

Reports

List Reports

GET /reports

Get a paginated list of company announcements.

Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	50	Results per page (max 100)
`company`	string	-	Filter by ASX code
`type`	string	-	Filter by report type
`from`	string	-	From date (YYYY-MM-DD)
`to`	string	-	To date (YYYY-MM-DD)
`search`	string	-	Search in title
`format`	string	json	Output format: json, csv, tsv

Get Report by Hash

GET /reports/:hash

Get a specific report by hash.

Path Parameters:

Parameter	Type	Description
`hash`	string	Report hash

Common Patterns

Pagination

Use page and per_page to paginate results:

# First page
curl "https://api.canetoad.ai/api/v1/companies?page=1&per_page=100"

# Second page
curl "https://api.canetoad.ai/api/v1/companies?page=2&per_page=100"

Filtering

Combine multiple filters:

curl "https://api.canetoad.ai/api/v1/companies?sector=Materials&active=true&sort=market_cap&order=desc"

CSV Export

Export data in CSV format for spreadsheets:

curl "https://api.canetoad.ai/api/v1/companies?format=csv&per_page=100" > companies.csv

API Reference

GET /companies

GET /companies/:code

GET /companies/:code/tenements

GET /companies/:code/subsidiaries

GET /tenements

GET /tenements/:id

GET /reports

GET /reports/:hash

On this page