{"openapi":"3.1.0","info":{"title":"EVE Contracts API","version":"1.0.0","description":"Read-only JSON access to public EVE Online contracts and derived analytics.\n\nNo authentication is required and no key is needed. Contracts are ingested from CCP ESI\nacross all EVE regions on a rolling 30-minute cycle; `date_issued` is CCP data while\n`first_seen_at` is when this service observed the contract.\n\nRate limit: 120 requests per 60s per client IP.\nResponses carry `X-RateLimit-*` headers; a 429 includes `Retry-After`.\n\nOnly public contracts are served. Contracts fetched with a user ESI token are never\nexposed here.","license":{"name":"Data sourced from CCP ESI","url":"https://developers.eveonline.com/"}},"servers":[{"url":"https://contracts.tovdc.com","description":"Production"}],"security":[],"tags":[{"name":"Contracts","description":"Search and read public contracts."},{"name":"Analytics","description":"Derived price, volume, and activity series."},{"name":"Reference","description":"Static lookups: regions, item types, filter codes."},{"name":"Meta","description":"Service index and dataset health."}],"paths":{"/api/v1":{"get":{"operationId":"getServiceIndex","tags":["Meta"],"summary":"Service index","description":"Lists every endpoint, the current rate limit, and links to the OpenAPI document and docs.","parameters":[],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: { name, version, endpoints: {…}, rate_limit: {…} } }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts":{"get":{"operationId":"listContracts","tags":["Contracts"],"summary":"Search public contracts","description":"Paginated search over every public contract we have ingested, across all EVE regions. Filters combine with AND. `q` matches the contract title OR the name of any included item, which is usually what you want — EVE contract titles are frequently blank or generic.","parameters":[{"name":"region_id","in":"query","required":false,"description":"Region id. Repeat or comma-separate for multiple. Also accepted as `region`.","example":"10000002","schema":{"type":"array","items":{"type":"integer"}},"style":"form","explode":true},{"name":"type","in":"query","required":false,"description":"Contract type. Repeatable.","schema":{"type":"array","items":{"type":"string","enum":["unknown","item_exchange","auction","courier","loan"]}},"style":"form","explode":true},{"name":"status","in":"query","required":false,"description":"Contract status. Repeatable. Omitted means everything except deleted/cancelled/reversed.","schema":{"type":"array","items":{"type":"string","enum":["outstanding","in_progress","finished_issuer","finished_contractor","finished","cancelled","rejected","failed","deleted","reversed"]}},"style":"form","explode":true},{"name":"availability","in":"query","required":false,"description":"Contract availability. Repeatable.","schema":{"type":"array","items":{"type":"string","enum":["public","personal","corporation","alliance"]}},"style":"form","explode":true},{"name":"category","in":"query","required":false,"description":"Match contracts containing at least one included item in this item category. Full list at /api/v1/categories.","example":"ship","schema":{"type":"string","enum":["ship","blueprint_original","blueprint_copy","blueprint","module","charge","drone","implant","skill","commodity","structure","structure_module","deployable","subsystem","fighter","skin","planetary","special_edition"]}},{"name":"q","in":"query","required":false,"description":"Case-insensitive substring match on contract title or included item names.","example":"Rattlesnake","schema":{"type":"string"}},{"name":"price_min","in":"query","required":false,"description":"Minimum price in ISK.","schema":{"type":"number"}},{"name":"price_max","in":"query","required":false,"description":"Maximum price in ISK.","schema":{"type":"number"}},{"name":"issuer_corporation_id","in":"query","required":false,"description":"Only contracts issued by this corporation. Also accepted as `issuer_corp`.","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort column.","schema":{"type":"string","enum":["date_issued","date_expired","price","volume","collateral"],"default":"date_issued"}},{"name":"dir","in":"query","required":false,"description":"Sort direction.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","required":false,"description":"1-based page number.","schema":{"type":"integer","default":1}},{"name":"page_size","in":"query","required":false,"description":"Results per page, 10–200. Also accepted as `limit`.","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContractSummary"}},"meta":{"$ref":"#/components/schemas/PageMeta"}},"required":["data","meta"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts/{contract_id}":{"get":{"operationId":"getContract","tags":["Contracts"],"summary":"Get one contract with its items","description":"Full contract record including the item list with blueprint metadata (runs, ME, TE, BPC/BPO) and resolved location names. 404s for contracts that are not public.","parameters":[{"name":"contract_id","in":"path","required":true,"description":"EVE contract id.","example":"234567890","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContractDetail"}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/regions":{"get":{"operationId":"listRegions","tags":["Reference"],"summary":"List EVE regions","description":"Every region id and name. Use `q` to search by name.","parameters":[{"name":"q","in":"query","required":false,"description":"Name substring filter.","example":"The Forge","schema":{"type":"string"}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ region_id, name }] }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/types":{"get":{"operationId":"listTypes","tags":["Reference"],"summary":"Look up item types","description":"Resolve an item name to a `type_id` (or a `type_id` back to a name). Backed by the EVE Static Data Export, so it covers every published type.","parameters":[{"name":"q","in":"query","required":false,"description":"Name search, minimum 2 characters. Required unless `id` is given.","example":"PLEX","schema":{"type":"string"}},{"name":"id","in":"query","required":false,"description":"Exact type id lookup.","example":"44992","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Max results, 1–100.","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ type_id, name }] }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","tags":["Reference"],"summary":"List item category filter codes","description":"Accepted values for the `category` parameter on /api/v1/contracts.","parameters":[],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ code, label, category_ids, is_blueprint_copy }] }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stats":{"get":{"operationId":"getStats","tags":["Meta"],"summary":"Dataset size and freshness","description":"Total and outstanding contract counts, contracts seen in the last 24h, and the timestamp of the most recent ingest. Check this before trusting a query built on the dataset.","parameters":[],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: { contracts_total, contracts_outstanding, contracts_last_24h, regions_with_contracts, latest_contract_seen_at } }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/prices":{"get":{"operationId":"getPriceHistory","tags":["Analytics"],"summary":"Hourly price history for an item in a region","description":"Min/median/max unit price per hour, derived from outstanding single-item item_exchange contracts. Multi-item bundles are excluded — their total price says nothing about the unit value of any one item in them.","parameters":[{"name":"type","in":"query","required":true,"description":"Item type id or name.","example":"PLEX","schema":{"type":"string"}},{"name":"region","in":"query","required":true,"description":"Region id or name.","example":"10000002","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Lookback window, 1–30.","schema":{"type":"integer","default":7}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ captured_at, min_price, median_price, max_price, sample_count, volume }], meta: {…} }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/volume":{"get":{"operationId":"getVolume","tags":["Analytics"],"summary":"Contracts posted per day, per region","description":"Long-form daily counts of newly seen public contracts for the busiest regions. One row per (day, region).","parameters":[{"name":"days","in":"query","required":false,"description":"Lookback window, 1–30.","schema":{"type":"integer","default":30}},{"name":"top_regions","in":"query","required":false,"description":"How many regions to include, ranked by activity. 1–50.","schema":{"type":"integer","default":8}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ day, region_id, region_name, contracts }], meta: {…} }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/issuers":{"get":{"operationId":"getIssuers","tags":["Analytics"],"summary":"Busiest contract issuers","description":"Leaderboard of public-contract issuers over a rolling window.","parameters":[{"name":"days","in":"query","required":false,"description":"Lookback window, 1–30.","schema":{"type":"integer","default":7}},{"name":"by","in":"query","required":false,"description":"Group by corporation or by character.","schema":{"type":"string","enum":["corp","character"],"default":"corp"}},{"name":"limit","in":"query","required":false,"description":"Max rows, 1–200.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ corporation_id | character_id, name, contracts, total_value }] }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/depth":{"get":{"operationId":"getMarketDepth","tags":["Analytics"],"summary":"Live contract depth for an item type","description":"Currently outstanding single-item item_exchange contracts for one type, cheapest unit price first. This is the live view; /analytics/prices is the historical rollup.","parameters":[{"name":"type","in":"query","required":true,"description":"Item type id or name.","example":"PLEX","schema":{"type":"string"}},{"name":"region","in":"query","required":false,"description":"Optional region id or name filter.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max rows, 1–200.","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Success.","headers":{"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"{ data: [{ contract_id, region_id, region_name, quantity, price, unit_price, url }], meta: {…} }"},"meta":{"type":"object","additionalProperties":true}},"required":["data"]}}}},"400":{"description":"Invalid or unresolvable parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honour `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ContractSummary":{"type":"object","properties":{"contract_id":{"type":"integer"},"type":{"type":"string"},"status":{"type":"string"},"availability":{"type":"string"},"issuer_id":{"type":"integer"},"issuer_corporation_id":{"type":"integer"},"region_id":{"type":["integer","null"]},"region_name":{"type":["string","null"]},"title":{"type":["string","null"]},"price":{"type":["number","null"],"description":"ISK."},"reward":{"type":["number","null"],"description":"ISK."},"collateral":{"type":["number","null"],"description":"ISK."},"volume":{"type":["number","null"],"description":"Cubic metres."},"date_issued":{"type":"string","format":"date-time"},"date_expired":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"}},"required":["contract_id","type","status","date_issued","date_expired"]},"ContractItem":{"type":"object","properties":{"record_id":{"type":"integer"},"type_id":{"type":"integer"},"type_name":{"type":["string","null"]},"quantity":{"type":"integer"},"raw_quantity":{"type":["integer","null"]},"is_included":{"type":"boolean","description":"false means the issuer is requesting this item, not offering it."},"is_singleton":{"type":"boolean"},"is_blueprint_copy":{"type":["boolean","null"],"description":"true = BPC, false = BPO, null = not a blueprint."},"runs":{"type":["integer","null"]},"material_efficiency":{"type":["integer","null"]},"time_efficiency":{"type":["integer","null"]}},"required":["record_id","type_id","quantity","is_included"]},"ContractDetail":{"allOf":[{"$ref":"#/components/schemas/ContractSummary"},{"type":"object","properties":{"source":{"type":"string","enum":["public_region"]},"for_corporation":{"type":"boolean"},"issuer_name":{"type":["string","null"]},"issuer_corporation_name":{"type":["string","null"]},"assignee_id":{"type":["integer","null"]},"acceptor_id":{"type":["integer","null"]},"start_location_id":{"type":["integer","null"]},"start_location_name":{"type":["string","null"]},"end_location_id":{"type":["integer","null"]},"end_location_name":{"type":["string","null"]},"buyout":{"type":["number","null"]},"days_to_complete":{"type":["integer","null"]},"date_accepted":{"type":["string","null"],"format":"date-time"},"date_completed":{"type":["string","null"],"format":"date-time"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ContractItem"}}},"required":["items"]}]},"PageMeta":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"query":{"type":"object","additionalProperties":true}},"required":["page","page_size","total"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"bad_request"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}