Wells Endpoints

Well-specific operations built on top of the knowledge graph. Wells are the most common entity type in AEGIS.

Endpoints

Well data is accessed through the knowledge-graph-service entity endpoints with the Well label:

Method	Path	Description
`POST`	`/entities`	Create a well (label: `Well`)
`GET`	`/entities/Well`	List all wells
`GET`	`/entities/Well/{id}`	Get well details
`PUT`	`/entities/Well/{id}`	Update well properties
`DELETE`	`/entities/Well/{id}`	Delete a well
`PUT`	`/entities/Well/{id}/production`	Update well production data
`GET`	`/edges/Well/{id}`	Get well relationships
`GET`	`/context/assemble/{api_number}`	Full well context assembly

List Wells


curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/entities/Well

Response (200):


{
  "entities": [
    {
      "entity_id": "well-001",
      "well_name": "Smith Ranch #1",
      "api_number": "42-383-12345",
      "operator": "Permian Energy Inc.",
      "status": "producing",
      "latitude": 31.9523,
      "longitude": -102.1245,
      "field": "Spraberry",
      "lease": "Smith Ranch"
    }
  ]
}

Get Well Details


curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/entities/Well/well-001

Create a Well


curl -X POST http://localhost:8000/entities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Well",
    "properties": {
      "entity_id": "well-new-001",
      "well_name": "Smith Ranch #4",
      "api_number": "42-383-67890",
      "operator": "Permian Energy Inc.",
      "status": "permitted",
      "latitude": 31.9530,
      "longitude": -102.1250
    }
  }'

Update Production Data

Special endpoint for updating well production metrics.


curl -X PUT http://localhost:8000/entities/Well/well-001/production \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oil_bbls": 1250,
    "gas_mcf": 3400,
    "water_bbls": 800,
    "reporting_month": "2026-03",
    "disposition_code_10_mcf": 50,
    "disposition_code_11_mcf": 0
  }'

Well Context Assembly

Retrieve comprehensive context for a well including all graph relationships, compliance status, and operational data. This is the same context that gets injected into agent prompts.


curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/context/assemble/42-383-12345

Response (200):


{
  "well": {
    "api_number": "42-383-12345",
    "well_name": "Smith Ranch #1",
    "operator": "Permian Energy Inc."
  },
  "lease": {"lease_name": "Smith Ranch", "lease_number": "12345"},
  "field": {"field_name": "Spraberry", "district": "08"},
  "offset_wells": [...],
  "flaring_authorizations": [...],
  "compliance_deadlines": [...],
  "infrastructure": [...]
}

Context assembly traverses the knowledge graph to collect 1-hop and 2-hop relationships, providing a complete picture of the well’s operational and regulatory context.