POST /v1/projects/{id}/spaces
Creates or returns a project Space. Idempotency-Key is required for every platform and binds the project, platform and initial User IDs (unordered except the iMessage creator in first position) for 24 hours after workflow completion. Concurrent matching requests join the same operation; conflicting reuse returns 422 once its outcome is available. A new email key creates a new thread; direct Spaces and SMS groups converge by participants. Every creation and successful replay requires at least one currently project-owned Agent, or for iMessage a shared-line Agent in a direct Space whose peer has an active Assignment of this project on that line. For iMessage, an existing exact match is reused; otherwise the first participant must be a project-owned dedicated phone Agent and creates the native direct chat or group. Multiple matching native groups return SPACE_AMBIGUOUS; incomplete group membership cannot establish an exact match. Replays return 200 and the current stored Space, with Idempotent-Replayed: true. A timeout does not cancel accepted work: retry the same key and input.
- TypeScript
- Python
- Rust
- Go
TypeScript
Parameters
string
required
string
required
Required for every platform; 1-255 visible ASCII characters. Reuse for retries. For email, the same key and initial participants retrieve the same Space, and a new key starts a separate conversation. SMS identifies its Space by participants, even with a new key. iMessage binds the key to the first participant as creator and the remaining unordered User IDs. Existing matching Spaces are reused.
Body
array of string
required
Canonical Photon User IDs from this project and platform. iMessage uses the first participant as creator when a new chat is needed; remaining order is ignored. Other platforms ignore all participant order. Counts: iMessage 2-1000; both WhatsApp platforms exactly 2; email 1-51; SMS 2-9. Every Space requires a currently project-owned Agent.
Platform
required
Returns
200 The Space already existed and is returned in its authoritative stored state. PlatformSpace
Headers: Cache-Control. The raw response carries these headers; see Raw responses.
string (date-time)
required
When Photon first persisted this resource.
TelegramSpaceDetails
required
string
required
string
required
ResourceMetadata
required
array of string
required
Platform
required
string
required
string (date-time)
required
When Photon last persisted a change to this resource’s public state.
201 The Space was created. PlatformSpace
Headers: Cache-Control, Location. The raw response carries these headers; see Raw responses.
string (date-time)
required
When Photon first persisted this resource.
TelegramSpaceDetails
required
string
required
string
required
ResourceMetadata
required
array of string
required
Platform
required
string
required
string (date-time)
required
When Photon last persisted a change to this resource’s public state.