Editing Data API (section)

== Conventions ==

{| class="wikitable"
|-
! Topic
! Rule
|-
| Endpoint
| <code><nowiki>POST https://bconomy.net/api/data</nowiki></code>
|-
| Authentication
| <code><nowiki>x-api-key</nowiki></code> header on every request
|-
| Query
| <code><nowiki>type</nowiki></code> field in the JSON body, written as <code><nowiki>area/name</nowiki></code> (for example <code><nowiki>market/listings</nowiki></code>); other fields are that query's parameters
|-
| IDs
| <code><nowiki>id</nowiki></code> is a BcID for player queries and the object's own ID for pets, eggs and factions; each endpoint says which
|-
| Dates
| Fields documented as ISO 8601 are strings; fields documented as Unix ms are numbers of milliseconds since 1970
|-
| Pagination
| <code><nowiki>page</nowiki></code> is 1-based; <code><nowiki>pageSize</nowiki></code> is optional unless an endpoint says otherwise
|-
| Large numbers
| Some totals can exceed <code><nowiki>Number.MAX_SAFE_INTEGER</nowiki></code> and lose precision in JavaScript; those fields are marked
|-
| Rate limit
| 120 requests per minute, counted per IP address and per BcID; heavy API use also slows your own Web Client
|-
| Versioning
| None. Fields can be added, changed or removed without notice
|}

=== Errors ===

Errors return a JSON body of <code><nowiki>{ "error": string }</nowiki></code>:

{| class="wikitable"
|-
! Status
! Meaning
|-
| <code><nowiki>400</nowiki></code>
| The game rejected the request, for example when you are over the rate limit. <code><nowiki>error</nowiki></code> explains why
|-
| <code><nowiki>403</nowiki></code>
| The query type exists but is not available through the HTTP API
|-
| <code><nowiki>500</nowiki></code>
| Anything else, including a missing or invalid key, an unknown <code><nowiki>type</nowiki></code>, or invalid parameters
|}