Skip to main content

Project Formations API Reference

The project routes under /v1/projects/{projectId}/formations work with a single project's formations. They follow the same workflows as the top-level routes. Read the Formations API Reference first: it covers importing, jobs, how bases are resolved, reading points and validation.

This page covers what is different on a project route.

Differences from the Top-Level Routes​

OperationOn a project route
List, get, HEAD, pointsOnly this project's formations. Company formations are not included. There are no scope or projectId filters; name is supported.
Import (PUT)Creates or replaces formations in this project
Update (PATCH)Only this project's formations. Others fail with 404 in their result.
DeleteOnly this project's formations
JobsOnly imports into this project

Project Formations Are a Separate Stack​

Each project's formations are independent of the company formations and of every other project's:

  • A name only has to be unique within the project. A project formation can have the same name as a company formation; they are different formations.
  • PUT on a project route matches names against this project's formations only. It never replaces or adjusts a company formation.
  • Bases are resolved within the project's formations only. Company formations are not part of the stack. See How Bases Are Resolved.

Example: Import into a Project​

PUT /v1/projects/{projectId}/formations?overlapHandling=trim   → 202 { jobId }
GET /v1/projects/{projectId}/formations/jobs/{jobId}           → poll until successful
[
  {
    "name": "Formation A",
    "color": "#c0392b",
    "points": [
      { "latitude": 35.0, "longitude": -100.1, "topTvd": 8000.0 },
      { "latitude": 35.0, "longitude": -100.0, "topTvd": 8010.0 },
      { "latitude": 35.1, "longitude": -100.05, "topTvd": 8005.0 }
    ]
  }
]

Copying Formations Between Scopes​

A formation read from a project includes "scope": "project" and its projectId. Sending it back to the same project's PUT works unchanged. Sending it to a different project, or to PUT /v1/formations, returns 400, so a formation can't be copied to the wrong place by mistake.

To copy a formation into another project or to the company:

  1. Read it, with all of its points, as described in Reading a formation in a form you can send back.
  2. Remove scope and projectId.
  3. PUT it on the destination route.

The copy is a new formation with its own id. Its enabled, maxDepth and maxThickness start at their defaults; set them with PATCH once the import succeeds.