Add a hosted connection or validate and save a custom server. Only team owners can create connections. Retry a known failed hosted setup with the same name to resume its saved project; an unknown creation outcome requires operator reconciliation.
POST
/projects/{projectId}/analytics/connections
Authorization
Authorization
header
string
required
Enter the team access token with the Bearer prefix, e.g. "Bearer team_access_token"
Path Parameters
projectId
string
required
The owning Chunkify project ID.
Bodyapplication/json
Analytics connection settings.
name
string
required
Name identifies this connection in the dashboard.
type
string
required
Type specifies whether Chunkify manages the analytics project.
Available options:
hostedcustom
endpoint
string
Endpoint specifies the custom server base URL. Required for custom connections and omitted for hosted connections.
public_ingest_key
string
PublicIngestKey optionally enables preview tracking for a custom connection. Supply the public ingestion key for the same analytics project as read_key. It is returned in connection reads and used in browser code. Omit for hosted connections.
Pattern:
^(ck_public_[a-f0-9]{64})?$
read_key
string
ReadKey supplies a read-only project credential for a custom connection. Required for custom connections and omitted for hosted connections. Stored encrypted and never returned.
Responses
application/json
data
object
required
created_at
string
date-time
required
CreatedAt records when this connection was added.
default_for_dashboard
boolean
required
DefaultForDashboard selects this connection for Chunkify dashboard players, public previews, the playground and newly generated snippets. It does not change existing external players. At most one connection per project is selected.
endpoint
string
uri
required
Endpoint specifies the analytics server base URL. It does not configure the player.
id
string
required
Id identifies this saved analytics connection.
name
string
required
Name identifies this connection in the dashboard.
project_id
string
required
ProjectId identifies the owning Chunkify project.
status
string
required
Status indicates whether the connection is ready to read or requires setup repair.
Available options:
preparingreadyfailed
type
string
required
Type specifies whether Chunkify manages the analytics project.
Available options:
hostedcustom
updated_at
string
date-time
required
UpdatedAt records when this connection was last changed.
allowed_origins
string[]
AllowedOrigins lists additional website origins permitted to ingest events for a hosted connection. Shared installation origins remain allowed. An empty list clears project-specific origins. Custom servers manage origins on their own infrastructure.
last_checked_at
string
date-time
LastCheckedAt records the most recent successful connection check.
public_ingest_key
string
PublicIngestKey is the public browser ingestion key used by Chunkify previews and player examples. It cannot read or manage analytics. Hosted connections use their primary public key. Omitted when preview tracking is not configured.
Pattern:
^(ck_public_[a-f0-9]{64})?$
retention_seconds
integer
int64
RetentionSeconds is the last retention applied to a hosted project, in seconds. Omitted for custom connections.
Required range: x >= 0
status
"success"
string
required
public_key
string
PublicKey is the hosted ingestion key. It remains available as public_ingest_key on the connection. Omitted for custom connections.
Success.
application/json
error
object
required
code
400
integer
required
Code is the HTTP status code
Examples:
400
message
string
required
Message is a human-readable error description
Examples:
Invalid request parameters
type
"ValidationError"
string
required
Type indicates the error category
Available options:
ValidationError
status
"error"
string
required
Status indicates the response status "error"
Validation error.
application/json
error
object
required
Error response details
code
401
integer
required
Code is the HTTP status code
Examples:
401
message
string
required
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error.
application/json
error
object
required
Error response details
code
403
integer
required
Code is the HTTP status code
Examples:
403
message
string
required
Message is a human-readable error description
Examples:
Unauthorized to perform this action
type
"ForbiddenError"
string
required
Type indicates the error category
Available options:
ForbiddenError
status
"error"
string
required
Status indicates the response status "error"
Forbidden error.
application/json
error
object
required
Error response details
code
404
integer
required
Code is the HTTP status code
Examples:
404
message
string
required
Message is a human-readable error description
Examples:
Ressource not found
type
"NotFoundError"
string
required
Type indicates the error category
Available options:
NotFoundError
status
"error"
string
required
Status indicates the response status "error"
NotFound error.
application/json
error
object
required
Error response details
code
409
integer
required
Code is the HTTP status code
Examples:
409
message
string
required
Message is a human-readable error description
Examples:
source_unavailable: the original video is no longer accessible
type
"ConflictError"
string
required
Type indicates the error category
Available options:
ConflictError
status
"error"
string
required
Status indicates the response status "error"
The name is already used, setup is incomplete, or deletion needs reconciliation.
application/json
error
object
required
Error response details
code
429
integer
required
Code is the HTTP status code
Examples:
429
message
string
required
Message is a human-readable error description
Examples:
Rate limit exceeded
type
"TooManyRequestsError"
string
required
Type indicates the error category
Available options:
TooManyRequestsError
status
"error"
string
required
Status indicates the response status "error"
TooManyRequests error.
application/json
error
object
required
Error response details
code
503
integer
required
Code is the HTTP status code
Examples:
503
message
string
required
Message is a human-readable error description
Examples:
The service is temporarily unavailable; retry the request
type
"ServiceUnavailableError"
string
required
Type indicates the error category
Available options:
ServiceUnavailableError
status
"error"
string
required
Status indicates the response status "error"
The analytics server is unavailable or returned an incompatible response.