Add bulk_items endpoint

[emmanuelmathot]

This PR reflect de facto implementation of bulk items POST in stac-fastapi-pgstac

Proposed Changes:

1. Add POST /collections/{collectionId}/bulk_items

PR Checklist:

• This PR has no breaking changes.
• I have added my changes to the CHANGELOG or a CHANGELOG entry is not required.

[jonhealy1]

@m-mohr @ahmed-hassan19 Any thoughts on this pr?

[m-mohr]

Wasn't there already such functionality defined in the original endpoint or in OGC API - Features?

[m-mohr]

Okay, checked it: The existing POST /collections/{collectionId}/items already accepts a partial ItemCollection (see the second rule list under POST and postOrPutItemCollection in the OpenAPI definition), and stac-fastapi-pgstac implements that too. OGC API - Features - Part 4 only covers single resources and leaves batch/atomic operations to a future standard.

Also, the PR doesn't match stac-fastapi's /bulk_items: it takes a different request body (items keyed by id plus an insert/upsert method, not an ItemCollection), returns 200 instead of 201, and has a different response body.

I'd rather not specify a second endpoint for the same operation, unless I'm missing something important. The missing parts (partial-success reporting, and maybe upsert) could be solved on /items, as discussed in #20. If upsert is needed, it could be an option on /items as well.

[jonhealy1]

@m-mohr I see where you're coming from about not duplicating endpoints, but maybe having a dedicated endpoint like /bulk_items is actually the cleaner API design? Overloading POST /items to handle both single items and bulk batches relates to the HTTP status code contradictions in #20. A dedicated bulk route would let us return a proper partial-success summary without breaking the strict REST rules for single-item inserts.

[m-mohr]

But isn't items already overloaded? The partial ItemCollection is already defined there...

[ahmed-hassan19]

I agree with m-mohr. The spec already has separate rules for a single Item and an ItemCollection on /items, so a second route doesn't fix #20. It moves the same contradiction ("Must return 409" but "May create only some") to a new endpoint. If we define batch behaviour once on /items, as agreed in #20, the only new thing bulk_items offers is upsert, which could be an option on /items.

I can include this in the #20 PR.

[jonhealy1]

I'm ok with deprecating /bulk_items

[emmanuelmathot]

I am ok too. This PR is actually acting a de-facto usage because I discovered that /items is not implemented properly to insert bulk items.
curious to have the feedback from @vincentsarago @bitner and @gadomski

[vincentsarago]

sounds good to me as well

[vincentsarago]

Sorry I'm having second thoughts after reviewing stac-utils/stac-fastapi#987

If I summarize my understanding:

• our /collections/{collectionId}/items endpoints are overloaded and don't follow the OGC Feature Part 4 spec (for the inputs and outputs)
• the /bulk_items endpoints was created to overcome the initial limitation of the Specs.

I feel we should update the /items endpoint to match the OGC specs (see first when the Part 4 will be published, and if there are upcoming changes) and use /bulk_items for things not covered by the OGC Specs (multi items support).

[jonhealy1]

Looking closely at the OGC API - Features - Part 4 draft, it explicitly states in Section 1 (Scope):

"Note: Additional OGC Standards are planned to handle transactions that require batch or atomicity semantics."

Furthermore, Requirement 6 mandates that a successful POST must return a 201 with a Location header pointing to the newly added resource.

This confirms that OGC Part 4 was strictly designed for single-resource operations. By overloading POST /collections/{collectionId}/items to accept an ItemCollection, STAC didn't just overload the endpoint - we actively broke alignment with OGC's architecture, which explicitly defers batch operations to a separate standard. This overloading is the exact reason we are stuck in the #20 HTTP status code contradiction.

Instead of trying to hack partial-success batch reporting into the single-item OGC endpoint, should we:

1. Revert POST /items: Remove ItemCollection support so it aligns 100% with OGC Part 4 (strict single-item insert, returning 201 + Location header).
2. Embrace a Dedicated Batch Route: Standardize something like /bulk_items (or /items/batch) as our implementation of batch semantics, pending the future OGC batch standard. This frees us to design a proper 200 OK batch-summary response with partial success reporting and explicit upsert controls, without violating OGC Part 4 or REST principles.

[m-mohr]

My main critique here was only really that we should not have two similar solutions for the same problem. So I'd be in for strict OGC alignment, which is likely a 2.0.0 for our Transaction Extension due to the breaking removal of batch support and other small differences.

The batch transactions are OGC API - Features - Part 11, see https://github.com/opengeospatial/ogcapi-features/tree/master/proposals/atomic-batch-tx - It seems more complex than what bulk_items was though.

Issue with it is the dependency on OGC and it just evolving much slower. I doubt they would stop anyone from moving Part 4 and 11 forward though. Question is a bit how far Part 4 is - something to check with Clemens and Peter.

[jonhealy1]

We could create a separate API extension for bulk items and remove item_collection support from here

[ahmed-hassan19]

I'm changing my earlier position: jonhealy1's point about Part 4's scope is fair. Part 4 leaves batches to a separate standard, so the #20 contradiction comes from accepting an ItemCollection on /items at all. A single-item /items plus a separate bulk extension removes it and still leaves one solution per operation.

Two points from the current OGC drafts matter for the split:

• Part 4 draft.3 (20-002r2, now co-branded OGC API - Common - Part 5) permits create via PUT (201) when the collection declares supportsNonAutogeneratedResourceIds: true. That covers single-item upsert (PUT /collections/{collectionId}/items/{featureId} should be allowed for creation also #17).
• Part 11 (atomic-batch-tx) sets atomic or batch semantics in the request body ("semantic", default atomic). A success returns 200 with a summary of counts, the URIs of created resources, and an exceptions array. Part 4 draft.3 already defines Prefer: handling=lenient (RFC 7240 §4.4) as accepting content that fails validation, so it shouldn't mean "partial writes allowed" as I suggested in REST Contradiction: HTTP Status Codes for Non-Atomic ItemCollection Transactions #20.

Should the #20 status-code and partial-success contract move to the new bulk extension instead of this repo? If so, reusing Part 11's response member names would keep a later move to /transactions cheap.

[jonhealy1]

@ahmed-hassan19 I agree. @m-mohr @emmanuelmathot what do you think? I think @vincentsarago supports this.

[m-mohr]

Note that all of these are still drafts and can change over time. That's the reason why we departed from OGC alignment at 1.0.0 release and kept alignment as a todo for later. It might make sense to check with the editors at OGC first what their status is and what's still planned to change (maybe some issue triage helps).

Do we want to break multiple times? If not, I'd try to just fix whatever is currently needed and then break when OGC finally got through with a final releases. I don't have a strong opinion myself.

[ahmed-hassan19]

Agreed that we should break only once.
Hint: Part 4 moved to 1.0.0-draft.3 on 2026-09-21, and its call for implementations is open (opengeospatial/ogcapi-features#415). Batch is still a proposal (atomic-batch-tx, unchanged since April), and bulk creation in Part 4 is labelled future work (opengeospatial/ogcapi-features#1013). So Part 4 should settle well before batch does.

That allows a single break in two steps:

1. Now, in 1.x and without breaking anything: put batch in a separate bulk-items extension that carries the REST Contradiction: HTTP Status Codes for Non-Atomic ItemCollection Transactions #20 contract and uses Part 11's response names (summary, exceptions), and mark the ItemCollection body on POST /items as deprecated in favour of it.
2. When Part 4 is final: release 2.0.0, which drops the ItemCollection body and aligns with Part 4.

If that works for everyone, we can check with the editors at OGC on opengeospatial/ogcapi-features#415 what's still expected to change in Part 4 before step 2.

[jonhealy1]

@ahmed-hassan19 I think this sounds good