> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or expand a shared Situation > Accepts a strict JSON body containing story_id or event_uid, optional direction (back or forward), and optional situation_uid for explicit expansion. An Event with several supporting Stories returns 409 and requires story_id selection. An existing canonical Situation is reused for 0 QU when situation_uid is omitted. Creation or explicit expansion costs 5 QU and requires a paid subscription or active trial. Admitted work requires an Idempotency-Key header (8–128 letters, digits or ._:-); replay uses the recorded response, concurrent work returns 409, and another body with the same key returns 409. Errors release quota reservations. The shared stored identity is public to all readers; this does not create a private copy. ## OpenAPI ````yaml /api-reference/openapi-v2.json post /api/v2/situations openapi: 3.0.3 info: title: GDELT Cloud API v2 version: 2.0.0 description: >- Clean v2 REST API for generated GDELT Cloud structured Events, clustered Stories, linked Entities, summaries, admin1 discovery, significance ranking, and paginated article evidence. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0-1: each event's raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20, systemic importance 0.15, propagation potential 0.10, market sensitivity 0.10. When magnitude is unmeasured its term AND its 0.20 weight are both dropped. The four CAMEO+ metrics are rubric scores produced by published formulas - ordinal ranking signals, not measurements, probabilities, or predicted price moves. goldstein_scale is one canonical public metric, populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful. Story linked_event_count is a Story-to-Event link aggregate, not a distinct Event total. servers: - url: https://gdeltcloud.com description: Production - url: http://localhost:3000 description: Local development security: - ApiKeyAuth: [] tags: - name: Events description: Coded CAMEO+ / conflict events — search, fetch, and summarize. - name: Stories description: Clustered narratives (stories) and their articles. - name: Situations description: >- One real-world occurrence as the Stories and coded Events that belong to it — stored, adjudicated membership (`meta.situation_source: curated`) or a walked neighbourhood around a Story. Discovery, detail, four independently paged member lists, and the only write on the core surface (5 QU with an Idempotency-Key). - name: Entities description: >- People & organizations — resolve a name to an entity, then fetch its profile and tone. Also the publication activity journal (/api/v2/activity): observed evidence of what was published about identities and records — committed batches only, cursor-paged, never source intake. - name: Unified Search description: >- One fuzzy lookup across every id-space — start here with a name, take the entity id, then reuse it on every other surface. This is the resolver the rest of the API assumes you called first. - name: Media Intelligence description: >- Press-coverage tone over time and share of voice against a peer set. Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social signal is an admin-only preview. - name: Facilities description: >- Unified physical-asset directory — GEM energy assets, World Port Index ports and Epoch AI data centers on one keyed surface, resolved to spine owners. Requires the `can_use_facilities` entitlement. - name: Monitors description: >- Organization-shared scheduled checks over the Core API, with email and signed-webhook delivery. Monitor execution does not consume query units. - name: Geography description: >- Country context and admin-1 geography: /api/v2/countries (publication activity, reporting counts, dated economic and resource fundamentals, facility and office inventories, directory mode over every registered country) and admin-1 lookups. - name: Government description: >- US federal awards (USAspending) and foreign-influence registrations (DOJ NSD FARA), resolved onto the entity spine. Requires the `can_use_gov` entitlement. - name: Political Offices description: >- Public political offices and who holds them — legislatures, cabinets, heads of state, courts and IGO posts, with the office start/end dates the publisher states (valid time), resolved onto the entity spine. Actor context for geopolitical analysis; NOT a PEP or sanctions-screening tool. Requires the `can_use_offices` entitlement. - name: Filings description: >- SEC EDGAR filings, XBRL financials, and relations extracted from filing text. Requires the `can_use_filings` entitlement. - name: Reference Data description: >- The GLEIF Global LEI Index — legal-entity reference data, consolidation relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif` entitlement. - name: Energy description: Global Energy Monitor assets + ownership registry. - name: AI Compute description: >- Epoch AI datasets — models, hardware, data centers, companies and chip sales. Requires the `can_use_epoch_ai` entitlement. - name: Macro Finance description: >- FRED economic time series — catalog, point-in-time observations and releases. Requires the `can_use_macro` entitlement. - name: Screening and Reference description: >- Restricted-party lists, name screening and ownership-chain exposure. Requires the `can_use_screening` / `can_use_exposure` entitlement. Analytical coverage, not an audit-grade compliance control. - name: China description: >- China overseas development finance (AidData GCDF). Requires the `can_use_china` entitlement. - name: Maritime description: >- AIS-derived vessel flow — chokepoint transits, last-known vessel positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so coverage thins in open ocean. Requires the `can_use_maritime` entitlement. - name: Atlas Intelligence description: >- Geopolitical-risk and posture indices computed from GDELT Cloud’s own coded events, normalized to each place’s own frozen baseline. - name: Briefs description: Source-backed monitoring briefs. - name: Meta description: >- Machine-readable discovery: the value vocabularies, the endpoint contracts, and the query-unit cost model. Unmetered, so a client can check before it spends. paths: /api/v2/situations: post: tags: - Situations summary: Create or expand a shared Situation description: >- Accepts a strict JSON body containing story_id or event_uid, optional direction (back or forward), and optional situation_uid for explicit expansion. An Event with several supporting Stories returns 409 and requires story_id selection. An existing canonical Situation is reused for 0 QU when situation_uid is omitted. Creation or explicit expansion costs 5 QU and requires a paid subscription or active trial. Admitted work requires an Idempotency-Key header (8–128 letters, digits or ._:-); replay uses the recorded response, concurrent work returns 409, and another body with the same key returns 409. Errors release quota reservations. The shared stored identity is public to all readers; this does not create a private copy. operationId: create-situation-v2 parameters: - name: Idempotency-Key in: header required: true description: >- Stable key for one admitted creation or expansion. Reuse the same key and body to retry a timed-out request; a different body needs a new key. schema: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9._:-]{8,128}$ requestBody: required: true content: application/json: schema: type: object additionalProperties: false anyOf: - required: - story_id - required: - event_uid properties: story_id: type: string minLength: 1 maxLength: 256 event_uid: type: string minLength: 1 maxLength: 256 situation_uid: type: string minLength: 1 maxLength: 256 direction: type: string enum: - back - forward default: forward example: story_id: story_123 responses: '200': description: >- Created, expanded, or reused Situation. Reuse costs 0 QU; adjudication costs 5 QU. content: application/json: schema: $ref: '#/components/schemas/SituationCreationResponse' '400': description: >- `INVALID_BODY` — The request body is not a valid JSON object. `UNKNOWN_FIELD` — The request body contains a field the endpoint does not accept. `SEED_REQUIRED` — Neither a Story nor an Event seed was supplied for Situation creation. `INVALID_SEED` — A Situation seed or target identifier is empty, contains whitespace/control characters, or exceeds 256 characters. `INVALID_DIRECTION` — The Situation expansion direction is not back or forward. `IDEMPOTENCY_KEY_REQUIRED` — Admitted Situation work requires an Idempotency-Key of 8–128 letters, numbers or ._:- characters. '401': description: Missing or invalid API key '403': description: >- `SUBSCRIPTION_REQUIRED` — This action requires a paid subscription or an active trial. Signed-in browsing remains available with QU. '404': description: >- `STORY_NOT_FOUND` — The path named a Story with no settled row on any date, so there is no situation to assemble around it. Different from a Story that simply has no neighbours — that is an empty situation at HTTP 200. '409': description: >- `AMBIGUOUS_EVENT_SEED` — The Event has multiple supporting Stories, so the service cannot choose a Situation seed. `SEED_MISMATCH` — The selected Story does not support the supplied Event seed. `STORY_NOT_IN_SITUATION` — The seed is not a member of the requested Situation, or the target cannot be resolved. `IDEMPOTENCY_CONFLICT` — The Idempotency-Key was already used for a different Situation creation body. `CREATION_IN_PROGRESS` — A Situation creation request with this key is running or being recovered. '429': description: '`RATE_LIMITED` — Too many requests per minute.' '500': description: Server error '503': description: >- `CREATION_UNAVAILABLE` — Situation creation admission, its durable receipt, or completion recovery is temporarily unavailable. `CREATION_FAILED` — Situation creation or expansion did not complete; its reservation was cancelled and this receipt charged zero QU. `CREATION_INTERRUPTED` — An interrupted Situation request was recovered before a Situation was saved; no QU were charged. `ADJUDICATOR_UNAVAILABLE` — Situation adjudication is disabled or its service is unavailable; no creation charge was admitted. `EVENT_UNAVAILABLE` — The Event’s canonical serving identity could not be established. `ACCESS_UNAVAILABLE` — Current workspace or trial access could not be established. No access was granted by assumption. security: - ApiKeyAuth: [] components: schemas: SituationCreationResponse: type: object properties: success: type: boolean enum: - true situation_uid: type: string created: type: boolean reused: type: boolean added: type: number considered: type: number quota_units: oneOf: - type: number enum: - 0 - type: number enum: - 5 story_count: type: number empty_reason: type: string nullable: true required: - success - situation_uid - created - reused - added - considered - quota_units securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: gdelt_sk_... description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.' ````