v1 integration API

Read project data with an access key, track changes and write with version control.

Last updated: 10 November 2026

On this page

Getting started Endpoints Pagination and change stream Writes and errors Schema and application documentation

Getting started

External integration endpoints are under /api/v1. They require an access key in Authorization: Bearer; session cookies do not authenticate these endpoints. Key scope applies together with its owner's current organisation and project permissions.

Create an access key using a user session and store the secret securely.
Check identity and key scope with GET /api/v1/me.
Retrieve accessible projects with GET /api/v1/projects.
Page through features using a returned project identifier.
If writing is required, check oku and yaz scope, project role, region and module permissions.

GET /api/v1/projects
Authorization: Bearer ERISIM_ANAHTARI

Replace ERISIM_ANAHTARI with the secret beginning sgk_ from the creation response. Keep it out of URLs, application source code and logs.

Endpoints

Method and endpoint	Response and use
`GET /api/v1/me`	`user` and safe metadata for the key in use
`GET /api/v1/projects`	Array of accessible main projects; excludes design branches
`GET /api/v1/projects/{pid}`	Project information and visible feature counts
`GET /api/v1/projects/{pid}/features`	GeoJSON `FeatureCollection`, `next` and `cursor`
`GET /api/v1/projects/{pid}/features/{fid}`	One GeoJSON feature
`GET /api/v1/projects/{pid}/equipment`	Fiber equipment; `items` and `next`
`GET /api/v1/projects/{pid}/connections`	Fiber connections; `items` and `next`
`GET /api/v1/projects/{pid}/circuits`	Technical circuits; `items` and `next`
`GET /api/v1/projects/{pid}/changes`	Raw change records; `items` and `next`
`POST /api/v1/projects/{pid}/edit`	Atomic writes using the general editing contract

features accepts type and WGS 84 bbox=minLongitude,minLatitude,maxLongitude,maxLatitude filters. equipment and connections accept a node_id filter. Not every cookie-authenticated application endpoint, such as catalogue reading or file transfer, has a v1 equivalent; obtain endpoint names from this contract or the schema.

Pagination and change stream

Paged endpoints default to limit=1000 and accept 1–5,000. after is the identifier returned by the preceding page. Pass response next as the next request's after; next: null indicates the last page. The project list does not use this paged envelope.

The feature response's cursor is a project change identifier captured before the feature query. Save the first read's value to track intervening changes with GET /api/v1/projects/{pid}/changes?after={cursor}. The stream cursor is numeric; feature identifiers are strings. Process rows in increasing identifier order and persist the last successfully applied change identifier.

A disabled-module change row may carry gizli: true instead of before/after data. Rebuild the local view when key or user scope changes. Webhooks notify about changes; read detailed data through the API.

Writes and errors

POST /api/v1/projects/{pid}/edit uses the ops, version and temporary-identifier rules from Editing API. v1 requires request_id. Resending the same content with the same operation identifier for the same user and project returns the original result; different content returns 409. Send the current record version for updates and deletions.

The v1 error envelope always contains detail, kod and alan; detail may be an array for validation errors. Response headers include X-GIS-API-Surum: 1, X-GIS-Surum and Cache-Control: no-store. X-GIS-Surum is the application version. Retry-After in 429 responses gives the wait in seconds; v1 and OGC share the same per-key counter.

Schema and application documentation

GET /api/v1/openapi.json returns only the v1 contract; GET /api/v1/docs returns usage documentation shipped with the application. Both are public. The site's API reference shows the broader application-generated schema. Installation-administration paths in that schema depend on application mode; inclusion does not mean every path can be called with an access key.