Create or get a Space

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/spaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "participantIds": [
    "<string>"
  ]
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/spaces"

payload = { "participantIds": ["<string>"] }
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({participantIds: ['<string>']})
};

fetch('https://api.photon.codes/v1/projects/{id}/spaces', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/spaces",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participantIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/spaces"

	payload := strings.NewReader("{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.photon.codes/v1/projects/{id}/spaces")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/spaces")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "details": {},
  "id": "pho_spc_00000000000000000000000001",
  "kind": "direct",
  "metadata": {},
  "participantIds": [
    "pho_usr_00000000000000000000000001",
    "pho_usr_00000000000000000000000002"
  ],
  "platform": "whatsapp",
  "projectId": "pho_prj_00000000000000000000000001",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "details": {},
  "id": "pho_spc_00000000000000000000000001",
  "kind": "direct",
  "metadata": {},
  "participantIds": [
    "pho_usr_00000000000000000000000001",
    "pho_usr_00000000000000000000000002"
  ],
  "platform": "whatsapp",
  "projectId": "pho_prj_00000000000000000000000001",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "HTTP_ERROR",
  "status": 400,
  "title": "Request Failed",
  "type": "https://photon.codes/docs/problems/http-error"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "USER_NOT_FOUND",
  "status": 404,
  "title": "User Not Found",
  "type": "https://photon.codes/docs/problems/user-not-found"
}

{
  "code": "SPACE_AMBIGUOUS",
  "status": 409,
  "title": "Multiple Matching Spaces",
  "type": "https://photon.codes/docs/problems/space-ambiguous"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "status": 413,
  "title": "Payload Too Large",
  "type": "https://photon.codes/docs/problems/payload-too-large"
}

{
  "code": "SPACE_REQUIRES_OWNED_AGENT",
  "status": 422,
  "title": "Space Requires Owned Agent",
  "type": "https://photon.codes/docs/problems/space-requires-owned-agent"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "IDEMPOTENCY_UNAVAILABLE",
  "status": 503,
  "title": "Idempotency Unavailable",
  "type": "https://photon.codes/docs/problems/idempotency-unavailable"
}

{
  "code": "UPSTREAM_TIMEOUT",
  "status": 504,
  "title": "Upstream Service Timeout",
  "type": "https://photon.codes/docs/problems/upstream-timeout"
}

Spaces

Create or get a Space

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.

POST

projects

{id}

spaces

Create or get a Space

curl --request POST \
  --url https://api.photon.codes/v1/projects/{id}/spaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "participantIds": [
    "<string>"
  ]
}
'

import requests

url = "https://api.photon.codes/v1/projects/{id}/spaces"

payload = { "participantIds": ["<string>"] }
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({participantIds: ['<string>']})
};

fetch('https://api.photon.codes/v1/projects/{id}/spaces', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.photon.codes/v1/projects/{id}/spaces",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'participantIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.photon.codes/v1/projects/{id}/spaces"

	payload := strings.NewReader("{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.photon.codes/v1/projects/{id}/spaces")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.photon.codes/v1/projects/{id}/spaces")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"participantIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "details": {},
  "id": "pho_spc_00000000000000000000000001",
  "kind": "direct",
  "metadata": {},
  "participantIds": [
    "pho_usr_00000000000000000000000001",
    "pho_usr_00000000000000000000000002"
  ],
  "platform": "whatsapp",
  "projectId": "pho_prj_00000000000000000000000001",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
  "createdAt": "2026-01-01T00:00:00.000Z",
  "details": {},
  "id": "pho_spc_00000000000000000000000001",
  "kind": "direct",
  "metadata": {},
  "participantIds": [
    "pho_usr_00000000000000000000000001",
    "pho_usr_00000000000000000000000002"
  ],
  "platform": "whatsapp",
  "projectId": "pho_prj_00000000000000000000000001",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

{
  "code": "HTTP_ERROR",
  "status": 400,
  "title": "Request Failed",
  "type": "https://photon.codes/docs/problems/http-error"
}

{
  "code": "NOT_AUTHENTICATED",
  "status": 401,
  "title": "Not Authenticated",
  "type": "https://photon.codes/docs/problems/not-authenticated"
}

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "type": "https://photon.codes/docs/problems/forbidden"
}

{
  "code": "USER_NOT_FOUND",
  "status": 404,
  "title": "User Not Found",
  "type": "https://photon.codes/docs/problems/user-not-found"
}

{
  "code": "SPACE_AMBIGUOUS",
  "status": 409,
  "title": "Multiple Matching Spaces",
  "type": "https://photon.codes/docs/problems/space-ambiguous"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "status": 413,
  "title": "Payload Too Large",
  "type": "https://photon.codes/docs/problems/payload-too-large"
}

{
  "code": "SPACE_REQUIRES_OWNED_AGENT",
  "status": 422,
  "title": "Space Requires Owned Agent",
  "type": "https://photon.codes/docs/problems/space-requires-owned-agent"
}

{
  "code": "INTERNAL_ERROR",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://photon.codes/docs/problems/internal-error"
}

{
  "code": "UPSTREAM_FAILURE",
  "status": 502,
  "title": "Upstream Service Failure",
  "type": "https://photon.codes/docs/problems/upstream-failure"
}

{
  "code": "IDEMPOTENCY_UNAVAILABLE",
  "status": 503,
  "title": "Idempotency Unavailable",
  "type": "https://photon.codes/docs/problems/idempotency-unavailable"
}

{
  "code": "UPSTREAM_TIMEOUT",
  "status": 504,
  "title": "Upstream Service Timeout",
  "type": "https://photon.codes/docs/problems/upstream-timeout"
}

Authorizations

Authorization

string

header

required

Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.

Headers

idempotency-key

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.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]+$

Path Parameters

string

required

Pattern: ^pho_prj_[0-7][0-9a-hjkmnp-tv-z]{25}$

Body

application/json

participantIds

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.

Pattern: ^pho_usr_[0-7][0-9a-hjkmnp-tv-z]{25}$

platform

enum<string>

required

Available options:

sms,

email,

whatsapp,

whatsapp_business,

imessage,

telegram

Response

The Space already existed and is returned in its authoritative stored state.

createdAt

string<date-time>

required

When Photon first persisted this resource.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

details

object

required

string

required

Pattern: ^pho_spc_[0-7][0-9a-hjkmnp-tv-z]{25}$

kind

string

required

Minimum string length: 1

metadata

object

required

Show child attributes

participantIds

string[]

required

Pattern: ^pho_usr_[0-7][0-9a-hjkmnp-tv-z]{25}$

platform

enum<string>

required

Available options:

sms,

email,

whatsapp,

whatsapp_business,

imessage,

telegram

Allowed value: "sms"

projectId

string

required

Pattern: ^pho_prj_[0-7][0-9a-hjkmnp-tv-z]{25}$

updatedAt

string<date-time>

required

When Photon last persisted a change to this resource's public state.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

⌘I

Get started

Problems

Endpoints

Event Delivery WebSocket

Event schemas

Create or get a Space

Authorizations

Headers

Path Parameters

Body

Response