commonscomputer/cal.diy
4
0
Fork 0
Code Issues Pull Requests Actions 2.2k Packages Projects Releases Wiki Activity

docs: improve English naturalness in API v2 documentation (#22130)

Browse Source 
* docs: improve English naturalness in API v2 documentation

- Fix awkward API summary 'Find out when is an event type ready to be booked' to 'Get available time slots for an event type'
- Correct 'setup' vs 'set up' usage throughout documentation
- Fix OAuth capitalization consistency
- Improve 'api' to 'API' capitalization in v2 docs
- Enhance readability while preserving technical accuracy

Fixes unnatural English phrasing in titles, headers, descriptions, and summaries across API v2 documentation files.

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: add missing articles 'the' in API v2 documentation

- Fix 'How to Set Up API' to 'How to Set Up the API' in titles
- Add 'the' before 'API' in descriptions and summaries
- Fix grammar error 'all you need to is' to 'all you need to do is'
- Improve naturalness while maintaining technical accuracy

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: fix unnatural English in API v2 @ApiOperation summaries

- Fix grammatically incorrect 'conferencing apps oauths callback' to 'Conferencing app OAuth callback'
- Replace 'ooo' with 'out-of-office' in user-facing summaries for clarity
- Ensure consistent sentence case capitalization (only first letter capitalized)
- Remove trailing periods from summaries for consistency
- Fix awkward phrasing like 'Get by attribute id all of...' to more natural English
- Revert 'Introduction to the API v2' back to 'Introduction to API v2'
- Improve naturalness while maintaining technical accuracy

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* Update apps/api/v2/src/modules/slots/slots-2024-09-04/controllers/slots.controller.ts

* Update docs/api-reference/v2/openapi.json

* docs: fix setup/set up usage - use 'backend setup' (noun) not 'backend set up' (verb)

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: fix setup/set up verb usage - use 'set up' (verb) not 'setup' (verb)

- Fix 'You have to setup' → 'You have to set up' in quickstart.mdx
- Fix 'Setup environment variables' → 'Set up environment variables'
- Fix 'Setup root of your app' → 'Set up root of your app'
- Fix 'prompted to setup' → 'prompted to set up' in setup.mdx

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* Ran v2 locally to regen the doc json files

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
This commit is contained in:
Keith Williams
2025-07-03 23:47:09 +00:00
committed by GitHub
co-authored by Devin AI
parent 850ac8092f
commit 739ef153f6
22 changed files with 100 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts
+1 -1
View File
@@ -157,7 +157,7 @@ export class CalendarsController {
@ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
@Get("/:calendar/connect")
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Get oAuth connect URL" })
@ApiOperation({ summary: "Get OAuth connect URL" })
@ApiQuery({
name: "redir",
required: false,
apps/api/v2/src/modules/conferencing/controllers/conferencing.controller.ts
+2 -2
View File
@@ -87,7 +87,7 @@ export class ConferencingController {
@HttpCode(HttpStatus.OK)
@UseGuards(ApiAuthGuard)
@ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
@ApiOperation({ summary: "Get OAuth conferencing app auth url" })
@ApiOperation({ summary: "Get OAuth conferencing app auth URL" })
@ApiParam({
name: "app",
description: "Conferencing application type",
@@ -130,7 +130,7 @@ export class ConferencingController {
@Get("/:app/oauth/callback")
@UseGuards()
@Redirect(undefined, 301)
@ApiOperation({ summary: "conferencing apps oauths callback" })
@ApiOperation({ summary: "Conferencing app OAuth callback" })
@ApiParam({
name: "app",
description: "Conferencing application type",
apps/api/v2/src/modules/organizations/attributes/options/organizations-attributes-options.controller.ts
+2 -2
View File
@@ -134,7 +134,7 @@ export class OrganizationsAttributesOptionsController {
@Roles("ORG_MEMBER")
@PlatformPlan("ESSENTIALS")
@Get("/attributes/:attributeId/options/assigned")
@ApiOperation({ summary: "Get by attribute id all of the attribute options that are assigned to users" })
@ApiOperation({ summary: "Get all assigned attribute options by attribute ID" })
async getOrganizationAttributeAssignedOptions(
@Param("orgId", ParseIntPipe) orgId: number,
@Param("attributeId") attributeId: string,
@@ -158,7 +158,7 @@ export class OrganizationsAttributesOptionsController {
@Roles("ORG_MEMBER")
@PlatformPlan("ESSENTIALS")
@Get("/attributes/slugs/:attributeSlug/options/assigned")
@ApiOperation({ summary: "Get by attribute slug all of the attribute options that are assigned to users" })
@ApiOperation({ summary: "Get all assigned attribute options by attribute slug" })
async getOrganizationAttributeAssignedOptionsBySlug(
@Param("orgId", ParseIntPipe) orgId: number,
@Param("attributeSlug") attributeSlug: string,
apps/api/v2/src/modules/organizations/bookings/organizations-bookings.controller.ts
+1 -1
View File
@@ -34,7 +34,7 @@ export class OrganizationsBookingsController {
constructor(private readonly bookingsService: BookingsService_2024_08_13) {}
@Get("/")
@ApiOperation({ summary: "Get Organization Bookings" })
@ApiOperation({ summary: "Get organization bookings" })
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@HttpCode(HttpStatus.OK)
apps/api/v2/src/modules/organizations/conferencing/organizations-conferencing.controller.ts
+1 -1
View File
@@ -105,7 +105,7 @@ export class OrganizationsConferencingController {
@UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
@Get("/teams/:teamId/conferencing/:app/oauth/auth-url")
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Get OAuth conferencing app's auth url for a team" })
@ApiOperation({ summary: "Get OAuth conferencing app's auth URL for a team" })
async getTeamOAuthUrl(
@Req() req: Request,
@Headers("Authorization") authorization: string,
apps/api/v2/src/modules/organizations/delegation-credentials/organizations-delegation-credential.controller.ts
+2 -2
View File
@@ -52,7 +52,7 @@ export class OrganizationsDelegationCredentialController {
@HttpCode(HttpStatus.CREATED)
@Roles("ORG_ADMIN")
@PlatformPlan("SCALE")
@ApiOperation({ summary: "Save delegation credentials for your organization." })
@ApiOperation({ summary: "Save delegation credentials for your organization" })
async createDelegationCredential(
@Param("orgId", ParseIntPipe) orgId: number,
@GetUser() delegatedServiceAccountUser: User,
@@ -72,7 +72,7 @@ export class OrganizationsDelegationCredentialController {
@Patch("/:credentialId")
@Roles("ORG_ADMIN")
@PlatformPlan("SCALE")
@ApiOperation({ summary: "Update delegation credentials of your organization." })
@ApiOperation({ summary: "Update delegation credentials of your organization" })
async updateDelegationCredential(
@Param("orgId", ParseIntPipe) orgId: number,
@GetUser() delegatedServiceAccountUser: User,
apps/api/v2/src/modules/organizations/stripe/organizations-stripe.controller.ts
+3 -3
View File
@@ -65,7 +65,7 @@ export class OrganizationsStripeController {
@UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
@Get("/connect")
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Get stripe connect URL for a team" })
@ApiOperation({ summary: "Get Stripe connect URL for a team" })
async getTeamStripeConnectUrl(
@Req() req: Request,
@Headers("Authorization") authorization: string,
@@ -104,7 +104,7 @@ export class OrganizationsStripeController {
@UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
@Get("/check")
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Check team stripe connection" })
@ApiOperation({ summary: "Check team Stripe connection" })
async checkTeamStripeConnection(
@Param("teamId", ParseIntPipe) teamId: number
): Promise<StripCredentialsCheckOutputResponseDto> {
@@ -116,7 +116,7 @@ export class OrganizationsStripeController {
@UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
@Get("/save")
@Redirect(undefined, 301)
@ApiOperation({ summary: "Save stripe credentials" })
@ApiOperation({ summary: "Save Stripe credentials" })
async save(
@Query("state") state: string,
@Query("code") code: string,
apps/api/v2/src/modules/organizations/users/bookings/controllers/organizations-users-bookings-controller.ts
+1 -1
View File
@@ -34,7 +34,7 @@ export class OrganizationsUsersBookingsController {
@Get("/")
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@ApiOperation({ summary: "Get all bookings of an organization user" })
@ApiOperation({ summary: "Get all bookings for an organization user" })
async getOrganizationUserBookings(
@Param("orgId", ParseIntPipe) orgId: number,
@Param("userId", ParseIntPipe) userId: number,
apps/api/v2/src/modules/organizations/users/ooo/controllers/organizations-users-ooo-controller.ts
+5 -5
View File
@@ -66,7 +66,7 @@ export class OrganizationsUsersOOOController {
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@UseGuards(IsUserInOrg)
@ApiOperation({ summary: "Get all ooo entries of a user" })
@ApiOperation({ summary: "Get all out-of-office entries for a user" })
async getOrganizationUserOOO(
@Param("userId", ParseIntPipe) userId: number,
@Query() query: GetOutOfOfficeEntryFiltersDTO
@@ -84,7 +84,7 @@ export class OrganizationsUsersOOOController {
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@UseGuards(IsUserInOrg)
@ApiOperation({ summary: "Create an ooo entry for user" })
@ApiOperation({ summary: "Create an out-of-office entry for a user" })
async createOrganizationUserOOO(
@Param("userId", ParseIntPipe) userId: number,
@Body() input: CreateOutOfOfficeEntryDto
@@ -100,7 +100,7 @@ export class OrganizationsUsersOOOController {
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@UseGuards(IsUserInOrg, IsUserOOO)
@ApiOperation({ summary: "Update ooo entry of a user" })
@ApiOperation({ summary: "Update an out-of-office entry for a user" })
async updateOrganizationUserOOO(
@Param("userId", ParseIntPipe) userId: number,
@Param("oooId", ParseIntPipe) oooId: number,
@@ -118,7 +118,7 @@ export class OrganizationsUsersOOOController {
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@UseGuards(IsUserInOrg, IsUserOOO)
@ApiOperation({ summary: "Delete ooo entry of a user" })
@ApiOperation({ summary: "Delete an out-of-office entry for a user" })
async deleteOrganizationUserOOO(
@Param("oooId", ParseIntPipe) oooId: number
): Promise<UserOooOutputResponseDto> {
@@ -132,7 +132,7 @@ export class OrganizationsUsersOOOController {
@Get("/ooo")
@Roles("ORG_ADMIN")
@PlatformPlan("ESSENTIALS")
@ApiOperation({ summary: "Get all OOO entries of org users" })
@ApiOperation({ summary: "Get all out-of-office entries for organization users" })
async getOrganizationUsersOOO(
@Param("orgId", ParseIntPipe) orgId: number,
@Query() query: GetOrgUsersOutOfOfficeEntryFiltersDTO
apps/api/v2/src/modules/slots/slots-2024-09-04/controllers/slots.controller.ts
+2 -2
View File
@@ -58,7 +58,7 @@ export class SlotsController_2024_09_04 {
@Get("/")
@ApiOperation({
summary: "Find out when is an event type ready to be booked.",
summary: "Get available time slots for an event type",
description: `
There are 4 ways to get available slots for event type of an individual user:
@@ -290,7 +290,7 @@ export class SlotsController_2024_09_04 {
@Patch("/reservations/:uid")
@ApiOperation({
summary: "Updated reserved a slot",
summary: "Update a reserved slot",
})
@HttpCode(HttpStatus.OK)
async updateReservedSlot(
apps/api/v2/src/modules/stripe/controllers/stripe.controller.ts
+3 -3
View File
@@ -49,7 +49,7 @@ export class StripeController {
@Get("/connect")
@UseGuards(ApiAuthGuard)
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: "Get stripe connect URL" })
@ApiOperation({ summary: "Get Stripe connect URL" })
@ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
async redirect(
@Req() req: Request,
@@ -79,7 +79,7 @@ export class StripeController {
@Get("/save")
@UseGuards()
@Redirect(undefined, 301)
@ApiOperation({ summary: "Save stripe credentials" })
@ApiOperation({ summary: "Save Stripe credentials" })
/**
* Handles saving Stripe credentials.
* If both orgId and teamId are present in the callback state, the request is proxied to the organization/team-level endpoint;
@@ -151,7 +151,7 @@ export class StripeController {
@UseGuards(ApiAuthGuard)
@HttpCode(HttpStatus.OK)
@ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
@ApiOperation({ summary: "Check stripe connection" })
@ApiOperation({ summary: "Check Stripe connection" })
async check(@GetUser() user: UserWithProfile): Promise<StripCredentialsCheckOutputResponseDto> {
return await this.stripeService.checkIfIndividualStripeAccountConnected(user.id);
}
apps/api/v2/src/modules/webhooks/controllers/webhooks.controller.ts
+1 -1
View File
@@ -85,7 +85,7 @@ export class WebhooksController {
@Get("/")
@ApiOperation({
summary: "Get all webooks",
summary: "Get all webhooks",
description: "Gets a paginated list of webhooks for the authenticated user.",
})
async getWebhooks(
apps/api/v2/swagger/documentation.json
+24 -24
View File
@@ -1123,7 +1123,7 @@
"/v2/organizations/{orgId}/attributes/{attributeId}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptions",
"summary": "Get by attribute id all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute ID",
"parameters": [
{
"name": "Authorization",
@@ -1215,7 +1215,7 @@
"/v2/organizations/{orgId}/attributes/slugs/{attributeSlug}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptionsBySlug",
"summary": "Get by attribute slug all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute slug",
"parameters": [
{
"name": "Authorization",
@@ -1467,7 +1467,7 @@
"/v2/organizations/{orgId}/bookings": {
"get": {
"operationId": "OrganizationsBookingsController_getAllOrgTeamBookings",
"summary": "Get Organization Bookings",
"summary": "Get organization bookings",
"parameters": [
{
"name": "Authorization",
@@ -1763,7 +1763,7 @@
"/v2/organizations/{orgId}/delegation-credentials": {
"post": {
"operationId": "OrganizationsDelegationCredentialController_createDelegationCredential",
"summary": "Save delegation credentials for your organization.",
"summary": "Save delegation credentials for your organization",
"parameters": [
{
"name": "Authorization",
@@ -1831,7 +1831,7 @@
"/v2/organizations/{orgId}/delegation-credentials/{credentialId}": {
"patch": {
"operationId": "OrganizationsDelegationCredentialController_updateDelegationCredential",
"summary": "Update delegation credentials of your organization.",
"summary": "Update delegation credentials of your organization",
"parameters": [
{
"name": "Authorization",
@@ -3454,7 +3454,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "OrganizationsConferencingController_getTeamOAuthUrl",
"summary": "Get OAuth conferencing app's auth url for a team",
"summary": "Get OAuth conferencing app's auth URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -5761,7 +5761,7 @@
"/v2/organizations/{orgId}/users/{userId}/bookings": {
"get": {
"operationId": "OrganizationsUsersBookingsController_getOrganizationUserBookings",
"summary": "Get all bookings of an organization user",
"summary": "Get all bookings for an organization user",
"parameters": [
{
"name": "Authorization",
@@ -6048,7 +6048,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUserOOO",
"summary": "Get all ooo entries of a user",
"summary": "Get all out-of-office entries for a user",
"parameters": [
{
"name": "Authorization",
@@ -6150,7 +6150,7 @@
},
"post": {
"operationId": "OrganizationsUsersOOOController_createOrganizationUserOOO",
"summary": "Create an ooo entry for user",
"summary": "Create an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6211,7 +6211,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo/{oooId}": {
"patch": {
"operationId": "OrganizationsUsersOOOController_updateOrganizationUserOOO",
"summary": "Update ooo entry of a user",
"summary": "Update an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6278,7 +6278,7 @@
},
"delete": {
"operationId": "OrganizationsUsersOOOController_deleteOrganizationUserOOO",
"summary": "Delete ooo entry of a user",
"summary": "Delete an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6329,7 +6329,7 @@
"/v2/organizations/{orgId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUsersOOO",
"summary": "Get all OOO entries of org users",
"summary": "Get all out-of-office entries for organization users",
"parameters": [
{
"name": "Authorization",
@@ -8362,7 +8362,7 @@
"/v2/calendars/{calendar}/connect": {
"get": {
"operationId": "CalendarsController_redirect",
"summary": "Get oAuth connect URL",
"summary": "Get OAuth connect URL",
"parameters": [
{
"name": "Authorization",
@@ -8657,7 +8657,7 @@
"/v2/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "ConferencingController_redirect",
"summary": "Get OAuth conferencing app auth url",
"summary": "Get OAuth conferencing app auth URL",
"parameters": [
{
"name": "Authorization",
@@ -8718,7 +8718,7 @@
"/v2/conferencing/{app}/oauth/callback": {
"get": {
"operationId": "ConferencingController_save",
"summary": "conferencing apps oauths callback",
"summary": "Conferencing app OAuth callback",
"parameters": [
{
"name": "state",
@@ -10488,7 +10488,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/connect": {
"get": {
"operationId": "OrganizationsStripeController_getTeamStripeConnectUrl",
"summary": "Get stripe connect URL for a team",
"summary": "Get Stripe connect URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -10551,7 +10551,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/check": {
"get": {
"operationId": "OrganizationsStripeController_checkTeamStripeConnection",
"summary": "Check team stripe connection",
"summary": "Check team Stripe connection",
"parameters": [
{
"name": "teamId",
@@ -10582,7 +10582,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/save": {
"get": {
"operationId": "OrganizationsStripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11131,7 +11131,7 @@
"/v2/slots": {
"get": {
"operationId": "SlotsController_2024_09_04_getAvailableSlots",
"summary": "Find out when is an event type ready to be booked.",
"summary": "Get available time slots for an event type",
"description": "\n There are 4 ways to get available slots for event type of an individual user:\n\n 1. By event type id. Event type id can be of user and team event types. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By event type slug + username. Example '/v2/slots?eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 3. By event type slug + username + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 4. By usernames only (used for dynamic event type - there is no specific event but you want to know when 2 or more people are available). Example '/v2/slots?usernames=alice,bob&username=bob&organizationSlug=org-slug&start=2050-09-05&end=2050-09-06'. As you see you also need to provide the slug of the organization to which each user in the 'usernames' array belongs.\n\n And 3 ways to get available slots for team event type:\n\n 1. By team event type id. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By team event type slug + team slug. Example '/v2/slots?eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n 3. By team event type slug + team slug + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n All of them require \"start\" and \"end\" query parameters which define the time range for which available slots should be checked.\n Optional parameters are:\n - timeZone: Time zone in which the available slots should be returned. Defaults to UTC.\n - duration: Only use for event types that allow multiple durations or for dynamic event types. If not passed for multiple duration event types defaults to default duration. For dynamic event types defaults to 30 aka each returned slot is 30 minutes long. So duration=60 means that returned slots will be each 60 minutes long.\n - format: Format of the slots. By default return is an object where each key is date and value is array of slots as string. If you want to get start and end of each slot use \"range\" as value.\n - bookingUidToReschedule: When rescheduling an existing booking, provide the booking's unique identifier to exclude its time slot from busy time calculations. This ensures the original booking time appears as available for rescheduling.\n ",
"parameters": [
{
@@ -11437,7 +11437,7 @@
},
"patch": {
"operationId": "SlotsController_2024_09_04_updateReservedSlot",
"summary": "Updated reserved a slot",
"summary": "Update a reserved slot",
"parameters": [
{
"name": "cal-api-version",
@@ -11530,7 +11530,7 @@
"/v2/stripe/connect": {
"get": {
"operationId": "StripeController_redirect",
"summary": "Get stripe connect URL",
"summary": "Get Stripe connect URL",
"parameters": [
{
"name": "Authorization",
@@ -11562,7 +11562,7 @@
"/v2/stripe/save": {
"get": {
"operationId": "StripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11601,7 +11601,7 @@
"/v2/stripe/check": {
"get": {
"operationId": "StripeController_check",
"summary": "Check stripe connection",
"summary": "Check Stripe connection",
"parameters": [
{
"name": "Authorization",
@@ -13219,7 +13219,7 @@
},
"get": {
"operationId": "WebhooksController_getWebhooks",
"summary": "Get all webooks",
"summary": "Get all webhooks",
"description": "Gets a paginated list of webhooks for the authenticated user.",
"parameters": [
{
docs/api-reference/v2/openapi.json
+24 -24
View File
@@ -1123,7 +1123,7 @@
"/v2/organizations/{orgId}/attributes/{attributeId}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptions",
"summary": "Get by attribute id all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute ID",
"parameters": [
{
"name": "Authorization",
@@ -1215,7 +1215,7 @@
"/v2/organizations/{orgId}/attributes/slugs/{attributeSlug}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptionsBySlug",
"summary": "Get by attribute slug all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute slug",
"parameters": [
{
"name": "Authorization",
@@ -1467,7 +1467,7 @@
"/v2/organizations/{orgId}/bookings": {
"get": {
"operationId": "OrganizationsBookingsController_getAllOrgTeamBookings",
"summary": "Get Organization Bookings",
"summary": "Get organization bookings",
"parameters": [
{
"name": "Authorization",
@@ -1763,7 +1763,7 @@
"/v2/organizations/{orgId}/delegation-credentials": {
"post": {
"operationId": "OrganizationsDelegationCredentialController_createDelegationCredential",
"summary": "Save delegation credentials for your organization.",
"summary": "Save delegation credentials for your organization",
"parameters": [
{
"name": "Authorization",
@@ -1831,7 +1831,7 @@
"/v2/organizations/{orgId}/delegation-credentials/{credentialId}": {
"patch": {
"operationId": "OrganizationsDelegationCredentialController_updateDelegationCredential",
"summary": "Update delegation credentials of your organization.",
"summary": "Update delegation credentials of your organization",
"parameters": [
{
"name": "Authorization",
@@ -3454,7 +3454,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "OrganizationsConferencingController_getTeamOAuthUrl",
"summary": "Get OAuth conferencing app's auth url for a team",
"summary": "Get OAuth conferencing app's auth URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -5761,7 +5761,7 @@
"/v2/organizations/{orgId}/users/{userId}/bookings": {
"get": {
"operationId": "OrganizationsUsersBookingsController_getOrganizationUserBookings",
"summary": "Get all bookings of an organization user",
"summary": "Get all bookings for an organization user",
"parameters": [
{
"name": "Authorization",
@@ -6048,7 +6048,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUserOOO",
"summary": "Get all ooo entries of a user",
"summary": "Get all out-of-office entries for a user",
"parameters": [
{
"name": "Authorization",
@@ -6150,7 +6150,7 @@
},
"post": {
"operationId": "OrganizationsUsersOOOController_createOrganizationUserOOO",
"summary": "Create an ooo entry for user",
"summary": "Create an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6211,7 +6211,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo/{oooId}": {
"patch": {
"operationId": "OrganizationsUsersOOOController_updateOrganizationUserOOO",
"summary": "Update ooo entry of a user",
"summary": "Update an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6278,7 +6278,7 @@
},
"delete": {
"operationId": "OrganizationsUsersOOOController_deleteOrganizationUserOOO",
"summary": "Delete ooo entry of a user",
"summary": "Delete an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6329,7 +6329,7 @@
"/v2/organizations/{orgId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUsersOOO",
"summary": "Get all OOO entries of org users",
"summary": "Get all out-of-office entries for organization users",
"parameters": [
{
"name": "Authorization",
@@ -8362,7 +8362,7 @@
"/v2/calendars/{calendar}/connect": {
"get": {
"operationId": "CalendarsController_redirect",
"summary": "Get oAuth connect URL",
"summary": "Get OAuth connect URL",
"parameters": [
{
"name": "Authorization",
@@ -8657,7 +8657,7 @@
"/v2/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "ConferencingController_redirect",
"summary": "Get OAuth conferencing app auth url",
"summary": "Get OAuth conferencing app auth URL",
"parameters": [
{
"name": "Authorization",
@@ -8718,7 +8718,7 @@
"/v2/conferencing/{app}/oauth/callback": {
"get": {
"operationId": "ConferencingController_save",
"summary": "conferencing apps oauths callback",
"summary": "Conferencing app OAuth callback",
"parameters": [
{
"name": "state",
@@ -10488,7 +10488,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/connect": {
"get": {
"operationId": "OrganizationsStripeController_getTeamStripeConnectUrl",
"summary": "Get stripe connect URL for a team",
"summary": "Get Stripe connect URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -10551,7 +10551,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/check": {
"get": {
"operationId": "OrganizationsStripeController_checkTeamStripeConnection",
"summary": "Check team stripe connection",
"summary": "Check team Stripe connection",
"parameters": [
{
"name": "teamId",
@@ -10582,7 +10582,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/save": {
"get": {
"operationId": "OrganizationsStripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11131,7 +11131,7 @@
"/v2/slots": {
"get": {
"operationId": "SlotsController_2024_09_04_getAvailableSlots",
"summary": "Find out when is an event type ready to be booked.",
"summary": "Get available time slots for an event type",
"description": "\n There are 4 ways to get available slots for event type of an individual user:\n\n 1. By event type id. Event type id can be of user and team event types. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By event type slug + username. Example '/v2/slots?eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 3. By event type slug + username + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 4. By usernames only (used for dynamic event type - there is no specific event but you want to know when 2 or more people are available). Example '/v2/slots?usernames=alice,bob&username=bob&organizationSlug=org-slug&start=2050-09-05&end=2050-09-06'. As you see you also need to provide the slug of the organization to which each user in the 'usernames' array belongs.\n\n And 3 ways to get available slots for team event type:\n\n 1. By team event type id. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By team event type slug + team slug. Example '/v2/slots?eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n 3. By team event type slug + team slug + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n All of them require \"start\" and \"end\" query parameters which define the time range for which available slots should be checked.\n Optional parameters are:\n - timeZone: Time zone in which the available slots should be returned. Defaults to UTC.\n - duration: Only use for event types that allow multiple durations or for dynamic event types. If not passed for multiple duration event types defaults to default duration. For dynamic event types defaults to 30 aka each returned slot is 30 minutes long. So duration=60 means that returned slots will be each 60 minutes long.\n - format: Format of the slots. By default return is an object where each key is date and value is array of slots as string. If you want to get start and end of each slot use \"range\" as value.\n - bookingUidToReschedule: When rescheduling an existing booking, provide the booking's unique identifier to exclude its time slot from busy time calculations. This ensures the original booking time appears as available for rescheduling.\n ",
"parameters": [
{
@@ -11437,7 +11437,7 @@
},
"patch": {
"operationId": "SlotsController_2024_09_04_updateReservedSlot",
"summary": "Updated reserved a slot",
"summary": "Update a reserved slot",
"parameters": [
{
"name": "cal-api-version",
@@ -11530,7 +11530,7 @@
"/v2/stripe/connect": {
"get": {
"operationId": "StripeController_redirect",
"summary": "Get stripe connect URL",
"summary": "Get Stripe connect URL",
"parameters": [
{
"name": "Authorization",
@@ -11562,7 +11562,7 @@
"/v2/stripe/save": {
"get": {
"operationId": "StripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11601,7 +11601,7 @@
"/v2/stripe/check": {
"get": {
"operationId": "StripeController_check",
"summary": "Check stripe connection",
"summary": "Check Stripe connection",
"parameters": [
{
"name": "Authorization",
@@ -13219,7 +13219,7 @@
},
"get": {
"operationId": "WebhooksController_getWebhooks",
"summary": "Get all webooks",
"summary": "Get all webhooks",
"description": "Gets a paginated list of webhooks for the authenticated user.",
"parameters": [
{
docs/developing/guides/api/how-to-setup-api-in-a-local-instance.mdx
+2 -2
View File
@@ -1,8 +1,8 @@
---
title: "How to setup API in a local instance"
title: "How to Set Up the API in a Local Instance"
---
To test API in your local instance, you have the following pre-requisites:
To test the API in your local instance, you have the following pre-requisites:
<Steps>
<Step title="Clone the cal.com repository">
docs/platform/atoms/payment-form.mdx
+2 -2
View File
@@ -97,7 +97,7 @@ export default function Booker( props : BookerProps ) {
}
```
</Step>
<Step title="Setup a page for payments">
<Step title="Set up a page for payments">
We recommend setting up a separate page for the payment form for the sake of a smooth and streamlined flow, but you can also do it in the same page.
From the previous step, you get redirected to the payment page when the booking is created. You can now access the payment uid present in the query parameters and render the payment form atom.
@@ -136,4 +136,4 @@ Below video shows a demonstration of how we combined the event types atom and pa
<p></p>
<Info>Link to the example app can be found [here](https://github.com/calcom/cal.com/tree/main/packages/platform/examples/base)</Info>
<Info>Link to the example app can be found [here](https://github.com/calcom/cal.com/tree/main/packages/platform/examples/base)</Info>
docs/platform/event-types-hooks.mdx
+3 -3
View File
@@ -94,7 +94,7 @@ export default function EventType({ id }: { id: number }) {
The useCreateEventType hook allows you to create a new event type. This hook returns a mutation function that handles the event type creation process. The mutation function accepts an object with the following properties: ***lengthInMinutes*** which is the length of the event in minutes, ***title*** which is the title of the event, ***slug*** which is the slug of the event, and ***description*** which is the description of the event.
Below code snippet shows how to use the useCreateEventType hook to setup an event type.
Below code snippet shows how to use the useCreateEventType hook to set up an event type.
```js
import { useCreateEventType } from "@calcom/atoms";
@@ -132,7 +132,7 @@ export default function CreateEventType() {
The useCreateTeamEventType hook allows you to create a new team event type. This hook returns a mutation function that handles the event type creation process. The mutation function accepts an object with the following properties: ***lengthInMinutes*** which is the length of the event in minutes, ***title*** which is the title of the event, ***slug*** which is the slug of the event, ***description*** which is the description of the event, schedulingType which can be either ***COLLECTIVE***, ***ROUND_ROBIN*** or ***MANAGED***, ***hosts*** which is an array of hosts for the event and the ***teamId*** which is the id of the team.
Below code snippet shows how to use the useCreateTeamEventType hook to setup a team event type.
Below code snippet shows how to use the useCreateTeamEventType hook to set up a team event type.
```js
import { useCreateTeamEventType } from "@calcom/atoms";
@@ -167,4 +167,4 @@ export default function CreateTeamEventType() {
</>
);
}
```
```
docs/platform/faq.mdx
+2 -2
View File
@@ -25,7 +25,7 @@ description: Answers to the most common questions about the Platform API and ato
### 5. What is an atom?
- An atom is a customizable UI component that handles scheduling on behalf of your user.
- Everything from the front-end to API calls is being handled by the atom, all you need to is import the atom and drop it in your code.
- Everything from the front-end to the API calls is being handled by the atom, all you need to do is import the atom and drop it in your code.
### 6. What are the minimum setup requirements for using atoms?
- You need to have a project that uses React version 18 and above.
@@ -51,4 +51,4 @@ Either of the two:
- If a booking is cancelled then you are not charged for it.
### 11. What happens if there are more bookings than in my plan?
- You have to pay overage for each booking that exceeds the amount in your plan.
- You have to pay overage for each booking that exceeds the amount in your plan.
docs/platform/guides/global-event-types.mdx
+3 -3
View File
@@ -3,11 +3,11 @@ title: Global event types
description: Event types that every managed user or a subset of managed users will have automatically
---
If you want that all of your managed users or a subset of managed users have the same event type setup automatically then follow along.
If you want all of your managed users or a subset of managed users to have the same event type set up automatically, then follow along.
## Prerequisites
1. You need to have an oAuth client setup, since we'll need the client id and client secret from the oauth client to be included in the api requests. Here is the link for the [oauth client setup guide](https://cal.com/docs/platform/quickstart)
1. You need to have an OAuth client set up, since we'll need the client id and client secret from the OAuth client to be included in the API requests. Here is the link for the [OAuth client setup guide](https://cal.com/docs/platform/quickstart)
2. You need to have an ESSENTIALS plan or higher
## Steps
@@ -19,7 +19,7 @@ managed event type and the event types created for managed users based on it are
3. Create managed users.
4. For each managed user you want to have this event type, create a membership within the team.
Then the managed user will have the event type created. Once you have steps 1 and 2 setup then you simply need to add the managed user to the team
Then the managed user will have the event type created. Once you have steps 1 and 2 set up, you simply need to add the managed user to the team
and the user will have the event type created. If you then update the parent managed event type then it will automatically update all of the children managed event types.
<Steps>
docs/platform/guides/teams-setup.mdx
+11 -11
View File
@@ -1,13 +1,13 @@
---
title: Configuring your team
description: Learn about how to setup teams via API v2
description: Learn how to set up teams via the API v2
---
This page guides you through the steps to setup teams via API v2. An organization is just a team that can have children teams.
This page guides you through the steps to set up teams via the API v2. An organization is just a team that can have children teams.
## Prerequisites
1. You need to have an oauth client setup, since we'll need the client id and client secret from the oauth client to be included in the api requests. Here is the link for the [oauth client setup guide](https://cal.com/docs/platform/quickstart)
1. You need to have an OAuth client set up, since we'll need the client id and client secret from the OAuth client to be included in the API requests. Here is the link for the [OAuth client setup guide](https://cal.com/docs/platform/quickstart)
2. You need to have an ESSENTIALS plan or above
3. In order to create a team and access team info you need to be an organization admin/owner
4. In order to create and access a team event type you need to be a team admin/owner
@@ -28,7 +28,7 @@ This page guides you through the steps to setup teams via API v2. An organizatio
}
```
The api response returned will look like below.
The API response returned will look like below.
```
{
"status": "success",
@@ -57,11 +57,11 @@ The api response returned will look like below.
}
}
```
We recommend storing the team id being returned back in the api response. This will be used in the next steps.
We recommend storing the team id being returned back in the API response. This will be used in the next steps.
</Step>
<Step>
The team created in the previous step has no members, hence we need to add managed users (members) to the team . To create a managed user here is the [managed user](https://cal.com/docs/api-reference/v2/platform-managed-users/create-a-managed-user) endpoint . After we're done creating a managed user, we need to create membership for the team which can be done by sending a POST request to the [add a member](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/create-a-membership) endpoint. The api response returned will look like below.
The team created in the previous step has no members, hence we need to add managed users (members) to the team . To create a managed user here is the [managed user](https://cal.com/docs/api-reference/v2/platform-managed-users/create-a-managed-user) endpoint . After we're done creating a managed user, we need to create membership for the team which can be done by sending a POST request to the [add a member](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/create-a-membership) endpoint. The API response returned will look like below.
```
{
"status": "success",
@@ -84,7 +84,7 @@ The team created in the previous step has no members, hence we need to add manag
</Step>
<Step>
Now that we have a team setup and it has members, we can create an event type for the team. To create an event type here is the [create an event type](https://cal.com/docs/api-reference/v2/orgs-event-types/create-an-event-type) endpoint. The request body would looks something like this:
Now that we have a team set up and it has members, we can create an event type for the team. To create an event type here is the [create an event type](https://cal.com/docs/api-reference/v2/orgs-event-types/create-an-event-type) endpoint. The request body would looks something like this:
```
{
"lengthInMinutes": 60,
@@ -95,7 +95,7 @@ Now that we have a team setup and it has members, we can create an event type fo
"hosts": [{"userId": 1399}]
}
```
The api response returned will look like below.
The API response returned will look like below.
```
{
"status": "success",
@@ -213,12 +213,12 @@ The api response returned will look like below.
}
}
```
We recommend storing the slug and team id being returned back in the api response. This will be used in the next steps.
We recommend storing the slug and team id being returned back in the API response. This will be used in the next steps.
</Step>
<Step>
Now that we have all the backend setup for teams, its time to setup the frontend. If we want to enable a team event type in the booker atom, we need to pass the prop `isTeamEvent` as true and also another additional prop `teamId`. The `teamId` is the id of the team that we created in the previous step. Here is the code snippet for the booker atom.
Now that we have all the backend setup for teams, it's time to set up the frontend. If we want to enable a team event type in the booker atom, we need to pass the prop `isTeamEvent` as true and also another additional prop `teamId`. The `teamId` is the id of the team that we created in the previous step. Here is the code snippet for the booker atom.
```
<Booker
isTeamEvent={true}
@@ -245,4 +245,4 @@ export default function TeamEvent(){
</Step>
</Steps>
</Steps>
docs/platform/quickstart.mdx
+4 -4
View File
@@ -95,7 +95,7 @@ We recommend setting the `timeZone` for ease of use.
## 4. Backend: setting up a refresh token endpoint
You have to setup an endpoint on your server to which atoms can send an expired access token and receive new one in return. This exchange will be automatically handled by atoms when you provide this endpoint URL when setting up frontend in the next step.
You have to set up an endpoint on your server to which atoms can send an expired access token and receive new one in return. This exchange will be automatically handled by atoms when you provide this endpoint URL when setting up frontend in the next step.
> Q: Why do we need a separate endpoint just for this?
A: Your OAuth client secret and users refresh tokens should never be exposed on the frontend. The OAuth client secret will reside as an environment variable in your backend and the users' refresh tokens are stored in your database, which are used by our API to refresh the access token.
@@ -105,7 +105,7 @@ You can check an example refresh token endpoint in our atoms examples app: [http
Shortly:
1. Setup environment variables or pass values directly. Here are ones from the examples app above:
1. Set up environment variables or pass values directly. Here are ones from the examples app above:
1. NEXT_PUBLIC_CALCOM_API_URL: [https://api.cal.com/v2](https://api.cal.com/v2)
2. NEXT_PUBLIC_X_CAL_ID: your OAuth client ID
3. X_CAL_SECRET_KEY - your OAuth client secret
@@ -156,7 +156,7 @@ pnpm:
pnpm add @calcom/atoms
```
### 6.2 Setup environment variables
### 6.2 Set up environment variables
CAL_OAUTH_CLIENT_ID: OAuth client ID
@@ -164,7 +164,7 @@ CAL_API_URL: [https://api.cal.com/v2](https://api.cal.com/v2)
REFRESH_URL: URL of the endpoint you implemented in step 3, for example, your.api.com/api/refresh
### 5.3 Setup root of your app
### 5.3 Set up root of your app
Next.js: open _app.js or or _app.tsx.
docs/platform/setup.mdx
+1 -1
View File
@@ -15,7 +15,7 @@ description: Get started with creating a platform account
</Step>
<Step title="Create your platform team">
After you sign up and create your account, go the [platform setup page](https://app.cal.com/settings/platform/new) where you are prompted to setup your platform team.
After you sign up and create your account, go the [platform setup page](https://app.cal.com/settings/platform/new) where you are prompted to set up your platform team.
<img src="/images/Platform_signup.png" />
</Step>