Invitations
An invitation asks a person by email to join the workspace with grants; create, send or withdraw one.
- GET
List invitations/workspaces /{workspace_id} /invitations - POST
Invite a person/workspaces /{workspace_id} /invitations - DELETE
Withdraw an invitation/workspaces /{workspace_id} /invitations /{id} - POST
Send an invitation email/workspaces /{workspace_id} /invitations /{id} /send
Invitation object
An invitation asks a person, by email, to join the workspace with the grants it lists once they accept.
iduuidrequiredThe invitation's id.
emailemailrequiredThe email address invited.
The grants the person holds once they accept, those you are shown.
other_grants booleanrequiredTrue when the invitation carries a grant you are not shown.
created_at date-timerequiredWhen the invitation was created.
updated_at date-timerequiredWhen the invitation last changed.
last_sent_at date-time or nullrequiredWhen the invitation email was last sent; null when it never was.
expires_at date-timerequiredWhen the invitation stops being valid. Sending it again moves this later.
invited_by_user_id string or nullrequiredThe user id of the member who sent the invitation. Null when no sender is recorded, when the sender has left, or when you are not shown them.
sender_removed booleanrequiredWhether the recorded sender is no longer a member.
List invitations
/workspaces/{workspace_id}/invitations Returns the workspace's pending invitations, each with the grants it carries, a page at a time, oldest first. Needs member.read; you see the invitations whose grants your reach contains, and every one you sent.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "invitations retrieved", "invitations": [ { "id": "1a7e0000-0000-4000-8000-000000000601", "email": "casey.nguyen@example.com", "grants": [ { "role_id": "analyst", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000103" ], "inherited": false, "other_orgs": false } } ], "other_grants": false, "created_at": "2026-11-08T09:00:00Z", "updated_at": "2026-11-08T09:00:00Z", "last_sent_at": "2026-11-08T09:00:00Z", "expires_at": "2027-02-06T09:00:00Z", "invited_by_user_id": "AlexRiveraExampleUserId00001", "sender_removed": false } ], "next_cursor": null}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
- any of
admin:readadmin:write - Privilege
member.read
Needs member.read. member.read applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.
Behavior
- Retry
- Safe to send again
- Paging
- Cursor · 1000 a page by default, up to 5000
Path parameters
workspace_id uuidrequiredThe workspace's id.
Query parameters
emailstringOnly invitations to this email address. One you are not shown answers an empty page, as one never sent does. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
limitintegerHow many invitations a page holds: 1 to 5000, 1000 by default.
cursorstringThe next_cursor of the previous page, with the same filters.
Response 200
The pending invitations you are shown, oldest first.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor, with the same filters, for the next page.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.NoAPP_API_ERR_BAD_PARAMETERS limit is not 1 to 5000, or cursor cannot be read or was sent with other filters.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold member.read. The same refusal comes when the path names a workspace other than the token's own.NoPlus the errors every call can return.
Related
Invite a person
/workspaces/{workspace_id}/invitations Invites an email address to the workspace with the grants it holds once accepted, or saves a pending invitation again: the one invitation_id names, or with invitation_id left out the email's own. Sending the same invitation_id again saves the same invitation, so a retry is safe. It returns 409 for an email that belongs to a member, whether or not you can see them, for an email with a pending invitation under a different invitation_id, and, with invitation_id left out, for one whose pending invitation carries grants you may not change. Needs member.manage, and each grant must sit inside what you may grant. Saving does not send the email; sending it is its own call.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": "casey.nguyen@example.com", "grants": [ { "role_id": "analyst", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000103" ] } } ], "invitation_id": "1a7e0000-0000-4000-8000-000000000601" }'$body = @{ email = "casey.nguyen@example.com" grants = @( @{ role_id = "analyst" scope = @{ kind = "selected" org_ids = @( "0a9e0000-0000-4000-8000-000000000103" ) } } ) invitation_id = "1a7e0000-0000-4000-8000-000000000601"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "email": "casey.nguyen@example.com", "grants": [ { "role_id": "analyst", "scope": { "kind": "selected", "org_ids": [ "0a9e0000-0000-4000-8000-000000000103", ], }, }, ], "invitation_id": "1a7e0000-0000-4000-8000-000000000601", },)response.raise_for_status(){ "message": "invitation saved", "id": "1a7e0000-0000-4000-8000-000000000601"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
member.manage
Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Read before sending again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
Request body
emailemailrequiredThe email address to invite. Required.
grantsarray of GrantRequestrequiredThe grants the person holds once they accept. An empty list invites with none, which needs member.manage over every organization. Required.
invitation_id uuid or nullThe invitation to save again, or the id to give a new one: a UUID, which you may choose. Left out, the email's pending invitation is saved again, or a new one is given a new id. A different id for an email with a pending invitation returns 409.
Response 200
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.NoAPP_API_ERR_MISSING_PARAMETER email is empty, grants is left out or null, or a grant names no role.NoAPP_API_ERR_BAD_PARAMETERS email holds no @, invitation_id is not a UUID, or a grant names a role the workspace does not have, or a malformed scope.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe grants reach beyond what you may grant, grants is empty and you do not hold member.manage over every organization, or the invitation saved again carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND invitation_id names an invitation of another workspace, or one you cannot see.No409APP_API_ERR_INVITATION_EMAIL_TAKEN The email belongs to a member, whether or not you can see them, a deleted account still in the workspace included; or it has a pending invitation and the body names a different invitation_id, or names none and that invitation carries grants you may not change.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Withdraw an invitation
/workspaces/{workspace_id}/invitations/{id} Withdraws a pending invitation, so it can no longer be accepted. Needs member.manage, and the invitation's grants must sit inside your reach.
- Request
- Response
- curl
- PowerShell
- Python
curl -X DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "invitation deleted"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
member.manage
Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Safe to repeat: ends in the same state
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe invitation's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The request carries a body other than nothing, null or {}: a delete takes none, and its options are query parameters; parameter names the body's first field, or body.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe invitation carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND No such pending invitation, or one you cannot see.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Send an invitation email
/workspaces/{workspace_id}/invitations/{id}/send Sends, or sends again, the email of a pending invitation, and moves its expiry 90 days out. Needs member.manage. Each API token may send 500 every 5 minutes, and a signed-in person 5 every 30 seconds; a send past that returns 429 with Retry-After.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "sent invitation"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
- Scope
admin:write- Privilege
member.manage
Needs member.manage. member.manage applies at each organization a grant covers and every organization below it.
Behavior
- Retry
- Read before sending again
- Audit log
- Recorded
Path parameters
workspace_id uuidrequiredThe workspace's id.
iduuidrequiredThe invitation's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No403APP_API_ERR_NO_PRIVILEGE token_scopeno_privilegeYou do not hold member.manage. The same refusal comes when the path names a workspace other than the token's own.NoAPP_API_ERR_BEYOND_OWN_AUTHORITY token_scopeThe invitation carries grants beyond your reach. cause is token_scope only when the token's scopes alone stand in the way: given every scope, with its other limits as they are, the token would make the change.No404APP_API_ERR_RECORD_NOT_FOUND No such pending invitation in the workspace, checked before your privilege.No409APP_API_ERR_CONFLICT The invitation was declined.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.No429APP_API_ERR_TOO_MANY_REQUESTS send_limitYou sent more invitations than the send limit allows (cause send_limit); Retry-After says when to try again.After Retry-AfterPlus the errors every call can return.