Reference
Tickets reference.
Generated XRPC reference, field-level schemas, payload schemas, lexicons, errors, security, public review, and glossary.
Developer beta
SDK beta 0.0.0-beta.2
29 ticket lexicons
Multi-app shared config roadmap
Lexicons
Atmosphere Tickets publishes under the reverse-DNS namespace
tickets.atmosphere.*. Public lexicons describe
portable catalog semantics and safe service contracts, not buyer
PII or checkout secrets.
tickets.atmosphere.ticketTier
Public ticket tier metadata linked to a community event and optional ATM product or price refs.
tickets.atmosphere.capacityGroup
Public label and visibility metadata for tiers that share capacity. Exact counters stay private.
tickets.atmosphere.checkInList
Public scanner-list metadata. Staff permissions and scan history stay private.
tickets.atmosphere.publicOffer
Intentional public offer metadata for discounts, presales, affiliates, or access windows.
createTicketEvent / updateTicketEvent
App-scoped ticketed-event config shell used by the ATM Tickets runtime.
Forms, waitlists, collaborations
Service methods cover attendee questions, waitlist entries/offers, and co-organizer collaboration records.
Generated XRPC reference
This table is generated from lexicons/tickets/atmosphere
so it stays aligned with the contract set used by the ATM runtime.
The JSON lexicons remain the source of truth; this reference is
the human-readable index.
| Method or record | Kind | Auth | Purpose | Links |
|---|---|---|---|---|
| tickets.atmosphere.acceptCollaboration | procedure | app service-auth | Accept a pending co-organizer invitation (dual-consent: app service-auth plus the co-organizer's own assertion). | |
| tickets.atmosphere.archiveTicketTier | procedure | app service-auth + organizer assertion | Archive an organizer-owned ATM Tickets tier. | |
| tickets.atmosphere.capacityGroup | record | organizer/app write path | Organizer-owned portable capacity group for a ticketed event. | |
| tickets.atmosphere.checkInList | record | organizer/app write path | Public check-in list label for an event. | |
| tickets.atmosphere.checkInTicket | procedure | scanner/app authority | Verify and check in a private ATM Tickets scan token. | |
| tickets.atmosphere.claimFreeTicket | procedure | app service-auth + buyer assertion | Atomically claim zero-price scarce tickets for a verified buyer without checkout redirect. | |
| tickets.atmosphere.claimWaitlistOffer | procedure | app service-auth | Claim a ticket waitlist OFFER by starting checkout against its already-reserved offer hold. | |
| tickets.atmosphere.createCapacityGroup | procedure | app service-auth + organizer assertion | Create an organizer-owned capacity group for a ticketed event. | |
| tickets.atmosphere.createTicketEvent | procedure | app service-auth | Create or upsert an organizer-owned ATM ticketed-event config shell. | |
| tickets.atmosphere.createTicketHold | procedure | app service-auth + buyer assertion | Atomically reserve ticket capacity and return an ATM checkout URL. | |
| tickets.atmosphere.createTicketTier | procedure | app service-auth + organizer assertion | Create an organizer-owned ATM Tickets tier and optional public ticket-tier refs for an event. | |
| tickets.atmosphere.defs | defs | app service-auth | No description in lexicon yet. | |
| tickets.atmosphere.getTicketAvailability | query | app service-auth | Read app-scoped ticket availability derived from private ATM holds and issued tickets. | |
| tickets.atmosphere.inviteOrganizerCollaboration | procedure | app service-auth | Invite a co-organizer to operationally co-run a ticketed event (Part A: operational delegation only). | |
| tickets.atmosphere.joinWaitlist | procedure | app service-auth | Join the FIFO waitlist for a sold-out ticket tier/capacity group. | |
| tickets.atmosphere.listBuyerTickets | query | app service-auth | List app-scoped issued tickets for a buyer or payment. | |
| tickets.atmosphere.listCollaborations | query | app service-auth | List organizer collaborations for an event (authorized via event control) or the calling co-organizer's own collaboration rows. | |
| tickets.atmosphere.listEventWaitlist | query | app service-auth | List an organizer's event waitlist: a per-capacity-group rollup plus the paginated FIFO queue, each entry with its position and current offer status. | |
| tickets.atmosphere.listOrganizerTickets | query | app service-auth | List app-scoped issued tickets for an organizer or event. | |
| tickets.atmosphere.listTicketFormResponses | query | app service-auth | List the full private attendee form responses for an organizer's own event. | |
| tickets.atmosphere.publicOffer | record | organizer/app write path | Public offer grouping for event tickets. | |
| tickets.atmosphere.releaseTicketHold | procedure | app service-auth | Release an active ticket hold before checkout completes. | |
| tickets.atmosphere.revokeCollaboration | procedure | app service-auth | Revoke a co-organizer collaboration. | |
| tickets.atmosphere.setTierForm | procedure | app service-auth | Set (or clear) the private per-tier attendee form for a ticketed event. | |
| tickets.atmosphere.ticketTier | record | organizer/app write path | Organizer-owned portable ticket tier metadata for an AT Protocol event. | |
| tickets.atmosphere.updateCapacityGroup | procedure | app service-auth + organizer assertion | Update an organizer-owned capacity group for a ticketed event. | |
| tickets.atmosphere.updateTicketEvent | procedure | app service-auth | Update an app-scoped ATM ticketed-event config shell. | |
| tickets.atmosphere.updateTicketTier | procedure | app service-auth + organizer assertion | Update organizer-owned ATM Tickets tier metadata. | |
| tickets.atmosphere.verifyTicket | procedure | scanner/app authority | Verify a private ATM Tickets scan token without mutating check-in state. |
Generated field reference
This section is regenerated from lexicons/tickets/atmosphere. It expands the contract index into field-level schema tables with location, type, required/nullable status, limits, and descriptions.
tickets.atmosphere.acceptCollaboration5 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | collaborationId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | coOrganizerDid | string | yes | no | format:did | The accepting co-organizer. |
| input | coOrganizerAssertionJwt | string | yes | no | maxLength:8192 | REQUIRED short-lived user service-auth JWT issued BY coOrganizerDid to ATM, scoped to tickets.atmosphere.acceptCollaboration. |
| output | collaboration | ref:tickets.atmosphere.defs#organizerCollaboration | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.archiveTicketTier5 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | tierId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| output | tier | ref:#tier | yes | no | none | No description in lexicon yet. |
| def:tier | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:tier | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
tickets.atmosphere.capacityGroup6 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| record | event | ref:com.atproto.repo.strongRef | yes | no | none | No description in lexicon yet. |
| record | name | string | yes | no | minLength:1, maxLength:1000, maxGraphemes:100 | No description in lexicon yet. |
| record | totalCapacity | integer | no | no | minimum:1, maximum:250000 | Organizer-configured capacity ceiling for this shared inventory pool. |
| record | archived | boolean | no | no | none | No description in lexicon yet. |
| record | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| record | updatedAt | string | no | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.checkInList5 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| record | event | ref:com.atproto.repo.strongRef | yes | no | none | No description in lexicon yet. |
| record | name | string | yes | no | minLength:1, maxLength:1000, maxGraphemes:100 | No description in lexicon yet. |
| record | archived | boolean | no | no | none | No description in lexicon yet. |
| record | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| record | updatedAt | string | no | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.checkInTicket8 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | ticketToken | string | yes | no | minLength:1, maxLength:4000 | No description in lexicon yet. |
| input | checkInListId | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | scannerDid | string | no | no | format:did | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| output | checkedInAt | string | no | no | format:datetime | No description in lexicon yet. |
| output | ticket | ref:tickets.atmosphere.defs#issuedTicket | no | no | none | No description in lexicon yet. |
tickets.atmosphere.claimFreeTicket15 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | eventId | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | eventUri | string | no | no | format:at-uri | No description in lexicon yet. |
| input | buyerDid | string | yes | no | format:did | No description in lexicon yet. |
| input | buyerAssertionJwt | string | yes | no | maxLength:8192 | Required short-lived user service-auth JWT from buyerDid to ATM, scoped to tickets.atmosphere.claimFreeTicket. |
| input | customerEmail | string | no | no | maxLength:320 | Private delivery/receipt hint for ticket emails. |
| input | items | array | yes | no | minLength:1, maxLength:20 | No description in lexicon yet. |
| input | idempotencyKey | string | no | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | claimId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | holdId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | environment | string | yes | no | maxLength:16 | No description in lexicon yet. |
| output | items | array | yes | no | minLength:1, maxLength:20 | No description in lexicon yet. |
| output | tickets | array | yes | no | minLength:1, maxLength:50 | No description in lexicon yet. |
| output | reused | boolean | no | no | none | No description in lexicon yet. |
tickets.atmosphere.claimWaitlistOffer15 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | waitlistId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | buyerDid | string | no | no | format:did | No description in lexicon yet. |
| input | buyerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from buyerDid to ATM, scoped to tickets.atmosphere.claimWaitlistOffer. |
| input | customerEmail | string | no | no | maxLength:320 | Private delivery/receipt hint. |
| input | returnUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| input | cancelUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| output | waitlistId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | holdId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | token | string | yes | no | maxLength:500 | No description in lexicon yet. |
| output | url | string | yes | no | maxLength:2000, format:uri | No description in lexicon yet. |
| output | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| output | expiresAt | string | yes | no | format:datetime | No description in lexicon yet. |
| output | amountCents | integer | yes | no | minimum:0 | No description in lexicon yet. |
| output | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
tickets.atmosphere.createCapacityGroup9 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | No description in lexicon yet. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.createCapacityGroup. |
| input | event | ref:tickets.atmosphere.defs#eventInput | yes | no | none | No description in lexicon yet. |
| input | name | string | yes | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | totalCapacity | integer | yes | no | minimum:1, maximum:250000 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | event | ref:tickets.atmosphere.defs#eventSummary | yes | no | none | No description in lexicon yet. |
| output | capacityGroup | ref:tickets.atmosphere.defs#capacityGroupSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.createTicketEvent7 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | No description in lexicon yet. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.createTicketEvent. |
| input | event | ref:tickets.atmosphere.defs#eventInput | yes | no | none | No description in lexicon yet. |
| input | status | string | no | no | maxLength:32 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | event | ref:tickets.atmosphere.defs#eventSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.createTicketHold20 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | eventId | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | eventUri | string | no | no | format:at-uri | No description in lexicon yet. |
| input | buyerDid | string | no | no | format:did | No description in lexicon yet. |
| input | buyerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from buyerDid to ATM. |
| input | customerEmail | string | no | no | maxLength:320 | Private delivery/receipt hint for ticket emails. |
| input | items | array | yes | no | minLength:1, maxLength:20 | No description in lexicon yet. |
| input | returnUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| input | cancelUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| input | idempotencyKey | string | no | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | holdId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | token | string | yes | no | maxLength:500 | No description in lexicon yet. |
| output | url | string | yes | no | maxLength:2000, format:uri | No description in lexicon yet. |
| output | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| output | expiresAt | string | yes | no | format:datetime | No description in lexicon yet. |
| output | amountCents | integer | yes | no | minimum:0 | No description in lexicon yet. |
| output | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| output | items | array | yes | no | minLength:1, maxLength:20 | No description in lexicon yet. |
| output | reused | boolean | no | no | none | No description in lexicon yet. |
tickets.atmosphere.createTicketTier19 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | No description in lexicon yet. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.createTicketTier. |
| input | event | ref:tickets.atmosphere.defs#eventInput | yes | no | none | No description in lexicon yet. |
| input | title | string | yes | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | description | string | no | no | maxLength:5000 | No description in lexicon yet. |
| input | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| input | unitAmount | integer | yes | no | minimum:0, maximum:2000000 | No description in lexicon yet. |
| input | maxPerOrder | integer | no | no | minimum:1, maximum:50 | No description in lexicon yet. |
| input | saleStartsAt | string | no | no | format:datetime | No description in lexicon yet. |
| input | saleEndsAt | string | no | no | format:datetime | No description in lexicon yet. |
| input | tierRef | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| input | productRef | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| input | priceRef | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| input | quantityTotal | integer | yes | no | minimum:1, maximum:250000 | No description in lexicon yet. |
| output | event | ref:tickets.atmosphere.defs#eventSummary | yes | no | none | No description in lexicon yet. |
| output | capacityGroup | ref:tickets.atmosphere.defs#capacityGroupSummary | yes | no | none | No description in lexicon yet. |
| output | tier | ref:tickets.atmosphere.defs#ticketTierSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.defs114 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| def:priceAmount | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| def:priceAmount | unitAmount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:eventInput | uri | string | yes | no | format:at-uri | No description in lexicon yet. |
| def:eventInput | cid | string | no | no | format:cid | No description in lexicon yet. |
| def:eventInput | title | string | yes | no | minLength:1, maxLength:3000, maxGraphemes:300 | No description in lexicon yet. |
| def:eventInput | startsAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:eventInput | imageUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:ticketHoldItemRequest | tierId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| def:ticketHoldItemRequest | quantity | integer | yes | no | minimum:1, maximum:50 | No description in lexicon yet. |
| def:ticketHoldItem | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketHoldItem | title | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketHoldItem | quantity | integer | yes | no | minimum:1, maximum:50 | No description in lexicon yet. |
| def:ticketHoldItem | unitAmount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:ticketHoldItem | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| def:ticketTierSummary | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketTierSummary | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketTierSummary | capacityGroupId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketTierSummary | title | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketTierSummary | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| def:ticketTierSummary | unitAmount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:ticketTierSummary | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:capacityGroupSummary | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:capacityGroupSummary | eventId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:capacityGroupSummary | name | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:capacityGroupSummary | totalCapacity | integer | yes | no | minimum:1 | No description in lexicon yet. |
| def:capacityGroupSummary | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:eventSummary | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:eventSummary | uri | string | yes | no | format:at-uri | No description in lexicon yet. |
| def:eventSummary | title | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:eventSummary | startsAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:organizerCollaboration | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:organizerCollaboration | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:organizerCollaboration | primaryOrganizerDid | string | yes | no | format:did | No description in lexicon yet. |
| def:organizerCollaboration | coOrganizerDid | string | yes | no | format:did | No description in lexicon yet. |
| def:organizerCollaboration | role | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:organizerCollaboration | status | string | yes | no | maxLength:16 | No description in lexicon yet. |
| def:organizerCollaboration | revenueShareBps | integer | no | no | minimum:0, maximum:10000 | Recorded revenue-share INTENT in basis points, for MANUAL RECONCILIATION ONLY. |
| def:organizerCollaboration | invitedAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:organizerCollaboration | acceptedAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:organizerCollaboration | revokedAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:ticketAvailability | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketAvailability | eventId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:ticketAvailability | title | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketAvailability | description | string | no | no | maxLength:5000 | No description in lexicon yet. |
| def:ticketAvailability | currency | string | no | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| def:ticketAvailability | unitAmount | integer | no | no | minimum:0 | No description in lexicon yet. |
| def:ticketAvailability | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:ticketAvailability | availableQuantity | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:ticketAvailability | heldQuantity | integer | no | no | minimum:0 | Quantity currently reserved by active holds. |
| def:ticketAvailability | soldQuantity | integer | no | no | minimum:0 | Quantity already issued/sold. |
| def:ticketAvailability | maxPerOrder | integer | yes | no | minimum:1, maximum:50 | No description in lexicon yet. |
| def:ticketAvailability | saleStartsAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:ticketAvailability | saleEndsAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:ticketHoldCheckout | holdId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketHoldCheckout | token | string | yes | no | maxLength:500 | No description in lexicon yet. |
| def:ticketHoldCheckout | url | string | yes | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:ticketHoldCheckout | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| def:ticketHoldCheckout | expiresAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:ticketHoldCheckout | amountCents | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:ticketHoldCheckout | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| def:ticketHoldCheckout | items | array | yes | no | minLength:1, maxLength:20 | No description in lexicon yet. |
| def:ticketHoldCheckout | reused | boolean | no | no | none | No description in lexicon yet. |
| def:ticketPresentation | iconUrl | string | yes | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:ticketPresentation | qr | ref:#ticketPresentationQr | yes | no | none | No description in lexicon yet. |
| def:ticketPresentation | app | ref:tickets.atmosphere.defs#brand | yes | no | none | No description in lexicon yet. |
| def:ticketPresentation | organizer | ref:tickets.atmosphere.defs#brand | yes | no | none | No description in lexicon yet. |
| def:ticketPresentation | event | ref:#ticketPresentationEvent | yes | no | none | No description in lexicon yet. |
| def:ticketPresentation | tier | ref:#ticketPresentationTier | yes | no | none | No description in lexicon yet. |
| def:brand | did | string | yes | no | format:did | No description in lexicon yet. |
| def:brand | handle | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:brand | name | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:brand | avatarUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:issuedTicket | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | paymentId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | claimId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | environment | string | yes | no | maxLength:16 | No description in lexicon yet. |
| def:issuedTicket | ownerDid | string | no | no | format:did | No description in lexicon yet. |
| def:issuedTicket | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:issuedTicket | ticketNumber | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicket | scanToken | string | no | no | maxLength:4000 | Private scan token returned only to authorized clients. |
| def:issuedTicket | scanUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:issuedTicket | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:issuedTicket | updatedAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:issuedTicketWithContext | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | paymentId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | claimId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | environment | string | yes | no | maxLength:16 | No description in lexicon yet. |
| def:issuedTicketWithContext | ownerDid | string | no | no | format:did | No description in lexicon yet. |
| def:issuedTicketWithContext | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
| def:issuedTicketWithContext | ticketNumber | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:issuedTicketWithContext | scanToken | string | no | no | maxLength:4000 | No description in lexicon yet. |
| def:issuedTicketWithContext | scanUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:issuedTicketWithContext | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:issuedTicketWithContext | updatedAt | string | yes | no | format:datetime | No description in lexicon yet. |
| def:issuedTicketWithContext | presentation | ref:tickets.atmosphere.defs#ticketPresentation | no | no | none | No description in lexicon yet. |
| def:issuedTicketWithContext | event | ref:tickets.atmosphere.defs#eventSummary | no | no | none | No description in lexicon yet. |
| def:issuedTicketWithContext | tier | ref:tickets.atmosphere.defs#ticketTierSummary | no | no | none | No description in lexicon yet. |
| def:verificationResult | valid | boolean | yes | no | none | No description in lexicon yet. |
| def:verificationResult | reason | string | no | no | maxLength:100 | No description in lexicon yet. |
| def:verificationResult | ticket | ref:tickets.atmosphere.defs#issuedTicket | no | no | none | No description in lexicon yet. |
| def:verificationResult | presentation | ref:tickets.atmosphere.defs#ticketPresentation | no | no | none | No description in lexicon yet. |
| def:verificationResult | event | ref:tickets.atmosphere.defs#eventSummary | no | no | none | No description in lexicon yet. |
| def:verificationResult | tier | ref:tickets.atmosphere.defs#ticketTierSummary | no | no | none | No description in lexicon yet. |
| def:ticketPresentationQr | enabled | boolean | yes | no | none | No description in lexicon yet. |
| def:ticketPresentationQr | label | string | yes | no | maxLength:100 | No description in lexicon yet. |
| def:ticketPresentationEvent | uri | string | yes | no | format:at-uri | No description in lexicon yet. |
| def:ticketPresentationEvent | title | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:ticketPresentationEvent | startsAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:ticketPresentationEvent | imageUrl | string | no | no | maxLength:2000, format:uri | No description in lexicon yet. |
| def:ticketPresentationTier | title | string | yes | no | maxLength:300 | No description in lexicon yet. |
tickets.atmosphere.getTicketAvailability2 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | event | ref:tickets.atmosphere.defs#eventSummary | no | no | none | No description in lexicon yet. |
| output | tiers | array | yes | no | maxLength:250 | No description in lexicon yet. |
tickets.atmosphere.inviteOrganizerCollaboration8 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | eventId | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | eventUri | string | no | no | format:at-uri | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | The inviting PRIMARY organizer (or an already-accepted co-organizer) authorizing this invite. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.inviteOrganizerCollaboration. |
| input | coOrganizerDid | string | yes | no | format:did | The DID being invited to co-organize the event. |
| input | revenueShareBps | integer | no | no | minimum:0, maximum:10000 | OPTIONAL recorded revenue-share INTENT in basis points (0..10000), for MANUAL RECONCILIATION ONLY between the primary organizer and the co-organizer. |
| output | collaboration | ref:tickets.atmosphere.defs#organizerCollaboration | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.joinWaitlist15 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | eventId | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | eventUri | string | no | no | format:at-uri | No description in lexicon yet. |
| input | tierId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | buyerDid | string | no | no | format:did | No description in lexicon yet. |
| input | buyerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from buyerDid to ATM, scoped to tickets.atmosphere.joinWaitlist. |
| input | customerEmail | string | no | no | maxLength:320 | Private delivery hint for the offer email. |
| input | quantity | integer | no | no | minimum:1, maximum:50 | No description in lexicon yet. |
| output | waitlistId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | status | string | yes | no | maxLength:16 | No description in lexicon yet. |
| output | position | integer | yes | no | minimum:0 | No description in lexicon yet. |
| output | quantity | integer | yes | no | minimum:1 | No description in lexicon yet. |
| output | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | capacityGroupId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | reused | boolean | no | no | none | No description in lexicon yet. |
tickets.atmosphere.listBuyerTickets2 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | tickets | array | yes | no | maxLength:100 | No description in lexicon yet. |
| output | cursor | string | no | no | maxLength:512 | No description in lexicon yet. |
tickets.atmosphere.listCollaborations2 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | collaborations | array | yes | no | maxLength:250 | No description in lexicon yet. |
| output | cursor | string | no | no | maxLength:512 | No description in lexicon yet. |
tickets.atmosphere.listEventWaitlist22 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | summaries | array | yes | no | maxLength:1000 | No description in lexicon yet. |
| output | entries | array | yes | no | maxLength:250 | No description in lexicon yet. |
| output | cursor | string | no | no | maxLength:512 | No description in lexicon yet. |
| def:summaries | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:summaries | capacityGroupId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:summaries | capacityGroupName | string | yes | no | maxLength:200 | No description in lexicon yet. |
| def:summaries | activeCount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:summaries | waitingCount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:summaries | offeredCount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:summaries | activeQuantity | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:entries | waitlistId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:entries | eventId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:entries | capacityGroupId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:entries | position | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:entries | quantity | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:entries | status | string | yes | no | maxLength:16 | No description in lexicon yet. |
| def:entries | buyerDid | string | no | no | format:did | No description in lexicon yet. |
| def:entries | customerEmailHint | string | no | no | maxLength:200 | No description in lexicon yet. |
| def:entries | offerHoldId | string | no | no | maxLength:300 | No description in lexicon yet. |
| def:entries | offeredAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:entries | offerExpiresAt | string | no | no | format:datetime | No description in lexicon yet. |
| def:entries | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.listOrganizerTickets2 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | tickets | array | yes | no | maxLength:250 | No description in lexicon yet. |
| output | cursor | string | no | no | maxLength:512 | No description in lexicon yet. |
tickets.atmosphere.listTicketFormResponses8 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| output | responses | array | yes | no | maxLength:250 | No description in lexicon yet. |
| output | cursor | string | no | no | maxLength:512 | No description in lexicon yet. |
| def:responses | ticketId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:responses | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:responses | fieldKey | string | yes | no | maxLength:64 | No description in lexicon yet. |
| def:responses | value | string | yes | no | maxLength:2000 | No description in lexicon yet. |
| def:responses | showAtCheckIn | boolean | yes | no | none | No description in lexicon yet. |
| def:responses | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.publicOffer9 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| record | event | ref:com.atproto.repo.strongRef | yes | no | none | No description in lexicon yet. |
| record | tiers | array | yes | no | none | No description in lexicon yet. |
| record | title | string | no | no | maxLength:1000, maxGraphemes:100 | No description in lexicon yet. |
| record | description | string | no | no | maxLength:10000, maxGraphemes:1000 | No description in lexicon yet. |
| record | startsAt | string | no | no | format:datetime | No description in lexicon yet. |
| record | endsAt | string | no | no | format:datetime | No description in lexicon yet. |
| record | archived | boolean | no | no | none | No description in lexicon yet. |
| record | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| record | updatedAt | string | no | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.releaseTicketHold6 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | holdId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | reason | string | no | no | maxLength:200 | No description in lexicon yet. |
| output | hold | ref:#hold | yes | no | none | No description in lexicon yet. |
| def:hold | id | string | yes | no | maxLength:300 | No description in lexicon yet. |
| def:hold | status | string | yes | no | maxLength:32 | No description in lexicon yet. |
tickets.atmosphere.revokeCollaboration5 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | collaborationId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | The revoking PRIMARY organizer (or accepted co-organizer) authorizing this revocation via event control. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.revokeCollaboration. |
| output | collaboration | ref:tickets.atmosphere.defs#organizerCollaboration | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.setTierForm15 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | tierId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | organizerDid | string | yes | no | format:did | No description in lexicon yet. |
| input | organizerAssertionJwt | string | no | no | maxLength:8192 | Optional short-lived user service-auth JWT from organizerDid to ATM, scoped to tickets.atmosphere.setTierForm. |
| input | form | ref:#form | no | yes | none | The attendee form schema. |
| output | tierId | string | yes | no | maxLength:300 | No description in lexicon yet. |
| output | fieldCount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| def:form | version | integer<1> | yes | no | none | No description in lexicon yet. |
| def:form | fields | array | yes | no | maxLength:30 | No description in lexicon yet. |
| def:formFields | key | string | yes | no | minLength:1, maxLength:64 | No description in lexicon yet. |
| def:formFields | label | string | yes | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| def:formFields | type | string | yes | no | maxLength:16 | No description in lexicon yet. |
| def:formFields | required | boolean | no | no | none | No description in lexicon yet. |
| def:formFields | showAtCheckIn | boolean | no | no | none | Show this answer at check-in. |
| def:formFields | options | array | no | no | maxLength:50 | No description in lexicon yet. |
tickets.atmosphere.ticketTier14 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| record | event | ref:com.atproto.repo.strongRef | yes | no | none | No description in lexicon yet. |
| record | title | string | yes | no | minLength:1, maxLength:1000, maxGraphemes:100 | No description in lexicon yet. |
| record | description | string | no | no | maxLength:10000, maxGraphemes:1000 | No description in lexicon yet. |
| record | currency | string | yes | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| record | unitAmount | integer | yes | no | minimum:0 | No description in lexicon yet. |
| record | capacityGroup | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| record | maxPerOrder | integer | no | no | minimum:1, maximum:50 | Organizer-configured per-order limit for this tier. |
| record | product | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| record | price | ref:com.atproto.repo.strongRef | no | no | none | No description in lexicon yet. |
| record | saleStartsAt | string | no | no | format:datetime | No description in lexicon yet. |
| record | saleEndsAt | string | no | no | format:datetime | No description in lexicon yet. |
| record | archived | boolean | no | no | none | No description in lexicon yet. |
| record | createdAt | string | yes | no | format:datetime | No description in lexicon yet. |
| record | updatedAt | string | no | no | format:datetime | No description in lexicon yet. |
tickets.atmosphere.updateCapacityGroup7 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | capacityGroupId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | name | string | no | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | totalCapacity | integer | no | no | minimum:1, maximum:250000 | No description in lexicon yet. |
| input | status | string | no | no | maxLength:32 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | capacityGroup | ref:tickets.atmosphere.defs#capacityGroupSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.updateTicketEvent9 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | eventId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | title | string | no | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | startsAt | string | no | yes | format:datetime | No description in lexicon yet. |
| input | eventCid | string | no | yes | format:cid | No description in lexicon yet. |
| input | imageUrl | string | no | yes | maxLength:2000, format:uri | No description in lexicon yet. |
| input | status | string | no | no | maxLength:32 | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| output | event | ref:tickets.atmosphere.defs#eventSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.updateTicketTier15 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | tierId | string | yes | no | minLength:1, maxLength:300 | No description in lexicon yet. |
| input | title | string | no | no | minLength:1, maxLength:200 | No description in lexicon yet. |
| input | description | string | no | yes | maxLength:5000 | No description in lexicon yet. |
| input | currency | string | no | no | minLength:3, maxLength:3 | No description in lexicon yet. |
| input | unitAmount | integer | no | no | minimum:0, maximum:2000000 | No description in lexicon yet. |
| input | maxPerOrder | integer | no | no | minimum:1, maximum:50 | No description in lexicon yet. |
| input | saleStartsAt | string | no | yes | format:datetime | No description in lexicon yet. |
| input | saleEndsAt | string | no | yes | format:datetime | No description in lexicon yet. |
| input | tierRef | ref:com.atproto.repo.strongRef | no | yes | none | No description in lexicon yet. |
| input | productRef | ref:com.atproto.repo.strongRef | no | yes | none | No description in lexicon yet. |
| input | priceRef | ref:com.atproto.repo.strongRef | no | yes | none | No description in lexicon yet. |
| input | metadata | unknown | no | no | none | No description in lexicon yet. |
| input | status | string | no | no | maxLength:32 | No description in lexicon yet. |
| output | tier | ref:tickets.atmosphere.defs#ticketTierSummary | yes | no | none | No description in lexicon yet. |
tickets.atmosphere.verifyTicket8 fields
| Location | Field | Type | Required | Nullable | Limits | Description |
|---|---|---|---|---|---|---|
| input | environment | string | no | no | maxLength:16 | No description in lexicon yet. |
| input | ticketToken | string | yes | no | minLength:1, maxLength:4000 | No description in lexicon yet. |
| output | valid | boolean | yes | no | none | No description in lexicon yet. |
| output | reason | string | no | no | maxLength:100 | No description in lexicon yet. |
| output | ticket | ref:tickets.atmosphere.defs#issuedTicket | no | no | none | No description in lexicon yet. |
| output | presentation | ref:tickets.atmosphere.defs#ticketPresentation | no | no | none | No description in lexicon yet. |
| output | event | ref:tickets.atmosphere.defs#eventSummary | no | no | none | No description in lexicon yet. |
| output | tier | ref:tickets.atmosphere.defs#ticketTierSummary | no | no | none | No description in lexicon yet. |
Contract tests
Tickets docs are checked against lexicons/tickets/atmosphere. Regenerate the reference after lexicon edits and run the contract check before sharing docs with app developers.
node scripts/generate-docs-reference.mjs
node scripts/check-docs-contracts.mjs
node scripts/check-examples.mjs- Every tickets.atmosphere NSID appears in docs.html and docs/generated-reference.json.
- Real docs pages are generated for overview, build, callbacks, reference, and operations.
- API examples document auth mode, request shape, and common failure behavior.
- Example server files include typecheck and smoke scripts for copied starter-kit code.
API reference
GET
tickets.atmosphere.getTicketAvailability
Read app-scoped availability derived from private holds, issued tickets, sale windows, and capacity groups.
GET /xrpc/tickets.atmosphere.getTicketAvailability?eventUri=at://...&environment=testPOST
tickets.atmosphere.createTicketHold
Atomically reserve ticket capacity and return an ATM checkout URL for paid tickets.
{
"eventUri": "at://...",
"buyerDid": "did:plc:buyer",
"buyerAssertionJwt": "...",
"items": [{ "ticketTierId": "tier_...", "quantity": 2 }]
}POST
tickets.atmosphere.claimFreeTicket
Claim a limited free ticket in-place using app service-auth plus a buyer assertion.
{
"eventUri": "at://...",
"buyerDid": "did:plc:buyer",
"buyerAssertionJwt": "...",
"ticketTierId": "tier_..."
}POST
tickets.atmosphere.checkInTicket
Verify and check in a private scan token. Repeat scans should return the existing check-in state.
{
"ticketToken": "opaque_scan_token",
"checkInListId": "list_..."
}XRPC methods
Use service calls for private inventory and ticket operations. ATM remains responsible for checkout initiation, settlement, receipts, app fees, and payment proofs.
POST tickets.atmosphere.createTicketEvent
POST tickets.atmosphere.updateTicketEvent
POST tickets.atmosphere.createTicketTier
POST tickets.atmosphere.updateTicketTier
POST tickets.atmosphere.archiveTicketTier
POST tickets.atmosphere.createCapacityGroup
POST tickets.atmosphere.updateCapacityGroup
POST tickets.atmosphere.setTierForm
GET tickets.atmosphere.getTicketAvailability
POST tickets.atmosphere.createTicketHold
POST tickets.atmosphere.releaseTicketHold
POST tickets.atmosphere.claimFreeTicket
POST tickets.atmosphere.joinWaitlist
POST tickets.atmosphere.claimWaitlistOffer
GET tickets.atmosphere.listEventWaitlist
GET tickets.atmosphere.listTicketFormResponses
POST tickets.atmosphere.inviteOrganizerCollaboration
POST tickets.atmosphere.acceptCollaboration
GET tickets.atmosphere.listCollaborations
POST tickets.atmosphere.revokeCollaboration
GET tickets.atmosphere.listBuyerTickets
GET tickets.atmosphere.listOrganizerTickets
POST tickets.atmosphere.verifyTicket
POST tickets.atmosphere.checkInTicketError codes
Ticketing errors should be stable enough for app developers to branch on, while still giving humans calm recovery copy.
| Code | HTTP | Retry | Developer action |
|---|---|---|---|
| TicketHoldUnavailable | 409 | no | Refresh availability and ask the buyer to choose a valid quantity. |
| TicketHoldExpired | 410 | no | Create a fresh hold before sending the buyer to checkout. |
| TicketAlreadyCheckedIn | 200 | no | Return the existing check-in state; do not record a second entry. |
| TicketTokenInvalid | 404 | no | Do not admit entry. Ask the organizer to inspect the ticket. |
| TicketVoided | 409 | no | Do not admit entry. The ticket was refunded, voided, or revoked. |
| OrganizerAssertionInvalid | 401 | no | Mint a fresh organizer assertion for tier or capacity setup. |
| BuyerAssertionInvalid | 401 | no | Mint a fresh buyer assertion for the claim or hold action. |
| ReceiverUnavailable | 502 | yes | Fix the app endpoint and redrive stored delivery attempts. |
Error decision trees
01
Sold out or hold unavailable
Refresh authoritative availability, ask the buyer to choose a lower quantity, and never proceed to checkout without a successful hold.
02
Buyer assertion invalid
Ask the app to mint a fresh assertion; fall back to guest-like checkout only if the app can safely fulfill without buyer DID binding.
03
Hold expired
Create a new hold and checkout. Do not reuse expired URLs or tokens.
04
Webhook failed
Fix receiver signature/raw-body handling, then redrive the stored delivery from ATM.
05
Duplicate check-in
Return the previous check-in state and show the scanner that the ticket was already used.
Security model
Tickets centralizes scarce private state while event apps keep the public event UX. Public records can describe safe catalog facts; private service state enforces capacity, issuance, verification, refunds, and check-in.
| Public | Event refs, public ticket tier metadata, safe capacity-group labels, public offers, and check-in list metadata. |
|---|---|
| Private | Exact inventory counters, holds, issued ticket ids, buyer emails, attendee answers, QR secrets, scan tokens, check-in logs, refunds, and fraud/risk state. |
| App auth | App service-auth controls module access, app fees, webhook routing, environment, and app-scoped visibility. |
| User assertions | Buyer and organizer assertions prove user intent without forcing another ATM sign-in or granting ATM an OAuth write session. |
- Never use public repo records or relay ordering to enforce scarce inventory.
- Never put raw scan tokens, buyer PII, attendee answers, or processor ids on protocol.
- Deduplicate webhooks and XRPC receiver events by delivery id.
- Use opaque QR/pass tokens and verify them through Tickets.
Threat model
| Threat | Risk | Primary control |
|---|---|---|
| Oversell | Concurrent buyers exceed capacity. | Private transactional holds and issued-ticket rows. |
| Buyer spoofing | App lies about buyer DID. | Short-lived buyer assertion with aud/lxm/jti checks. |
| Replay | Duplicate webhook or claim mutates twice. | Delivery ids and idempotency keys before side effects. |
| QR leakage | Ticket or buyer data leaks from passes. | Opaque scan tokens only; hash secrets privately. |
| Visibility creep | Apps see unrelated payment or attendee data. | App-scoped events, dashboards, and module permissions. |
Security diagrams
01
App service-auth
App DID mints a short-lived token for an exact Tickets method; ATM verifies issuer, audience, lxm, expiry, signature, and jti.
02
Organizer assertion
Organizer authorizes the event app to configure ticket tiers and capacity for a specific event context.
03
Buyer assertion
Buyer DID assertion binds a signed-in event-app buyer to a hold or free claim without forcing checkout re-auth.
04
QR verification
Opaque token is checked against private issued-ticket state; check-in mutates once and repeat scans return existing state.
05
Private/public boundary
Public event and tier refs are display/catalog only; holds, issued tickets, scan tokens, attendee answers, and check-ins stay private.
Compliance boundaries
ATM owns payment processing and processor coordination. Event apps own event UX and app-specific fulfillment. Tickets owns scarce ticket truth. Keep those boundaries visible in support, dashboards, and app developer docs.
| Actor | Can see | Must not see |
|---|---|---|
| Event app | Payments it originated, app fee data, ticket/order status needed for fulfillment. | Organizer KYC, bank details, connected-account ids, or other-app payments. |
| Organizer | Ticket sales, payouts, disputes, taxes, attendee data needed for the event. | App secrets, app webhook signatures, unrelated app fee routing. |
| Scanner | Opaque token status, event/tier display, check-in result. | Buyer email, payment id, processor id, raw QR secrets. |
| Public protocol | Safe event, tier, offer, and payment proof refs. | Attendee answers, exact counters, check-in logs, customer PII, fraud/risk state. |
Data ownership
The safest model is public where portability helps, private where scarcity or personal data matters. Apps can build rich event UX on public records while relying on Tickets for transactional truth.
| Data | Where it lives | Why |
|---|---|---|
| Event page | Community event lexicons and app-local display state | Portable event discovery and app-specific UX. |
| Ticket tier metadata | Public tickets.atmosphere.ticketTier plus private mirrors | Safe catalog facts can be public protocol state. |
| Inventory counters | Private Tickets tables | Needs transactions, locks, idempotency, and audit trails. |
| Buyer contact and attendee answers | Private app/Tickets state | Personal or fulfillment data should not be public protocol state. |
| Payment truth | ATM payment ledger and public proof state | Unified checkout, refunds, receipts, app fees, and policy-driven public payment proof state. |
| QR/wallet token | Private hashed token rows | Opaque, revocable scan authority. |
Feature map
Atmosphere Tickets can support Hi.Events-style capabilities, but the ownership split should stay sharp: centralized only where ticketing correctness requires it, public/on-protocol where portability helps, and app-owned where UX differs.
| Capability | Owner | Notes |
|---|---|---|
| Ticket tiers and capacity | Tickets | Scarce inventory must be transactional and shared across apps. |
| Promo codes and public offers | Tickets + ATM | Public offer metadata can be portable; redemption counters stay private. |
| Event SEO and discovery | Event apps | Apps own social discovery, event pages, and product-specific presentation. |
| Organizer dashboard | Event apps + ATM | Event-specific tools in apps, money/payment controls in ATM. |
| Order management | Tickets + apps | Ticket status in Tickets; attendee messaging and presentation in apps. |
| Analytics | ATM + apps | Money ledger in ATM, traffic/social/product analytics in the app. |
| Affiliate/campaign UX | Apps | Public offer refs can connect back to Tickets/ATM for redemption truth. |
Lexicon review
The ticket lexicons are designed for public catalog and service contracts, not ticket secrets. Community feedback should focus on whether records are portable, minimal, and safe to publish.
| Question | Why it matters |
|---|---|
| Are tier/capacity records generic enough? | Multiple event apps should be able to display and sell against the same event. |
| Should public offers stay in tickets.atmosphere? | Ticket offers may differ from generic product discounts. |
| Do assertion fields belong in service methods only? | Assertions are private action proofs and should not leak into public records. |
| Are check-in list records safe? | Scanner permissions and logs must remain private even if list metadata is public. |
| Is the namespace shape correct? | tickets.atmosphere.* should stay distinct from money.atmosphere.* payment contracts. |
Public review bundle
Share the raw lexicons, generated reference, threat model, integration flow, and open questions when asking the AT Protocol community to review Tickets contracts.
lexicons/tickets/atmosphere
Record and XRPC schemas for tier, capacity, offer, hold, availability, issuance, verification, and check-in.
docs/generated-reference.json
Machine-readable index for docs and review tools.
Privacy and interoperability
Check public/private boundaries, app/user auth, and whether another event app can integrate without private assumptions.
Regenerate docs
Update raw schemas, regenerate reference, run checks, and record feedback-driven changes.
Glossary
| Event app | The app that owns public event pages, discovery, organizer UX, buyer UX, and scanner screens. |
|---|---|
| Organizer | The user or project receiving ticket revenue and configuring ticketing for an event. |
| Repo | A user's public AT Protocol repository of signed records, such as event or ticket metadata records. |
| PDS | Personal Data Server: the service that hosts a user's account and repo. |
| Service-auth | AT Protocol Inter-Service Authentication: a short-lived JWT scoped to one XRPC method. |
| Ticket tier | A sellable or claimable ticket type for an event. |
| Capacity group | A private inventory bucket that one or more ticket tiers can share. |
| Hold | A short-lived transactional reservation before checkout or free claim completion. |
| Issued ticket | The private ticket truth created after payment confirmation or free claim success. |
| Buyer assertion | A short-lived user service-auth JWT proving the app saw this buyer for this action. |
| Organizer assertion | A short-lived user service-auth JWT proving the organizer authorized ticket configuration. |
| Scan token | An opaque private token embedded in a QR code, wallet pass, or scan URL. |
| Check-in list | The scanner context for verifying and recording entry. |