Class SanityClient

constructor

• new SanityClient(httpRequest: HttpRequest, config?: ClientConfig): SanityClient

  Parameters

  • httpRequest: HttpRequest
  • config: ClientConfig = defaultConfig

  Returns SanityClient

agent

assets

datasets

listen

live

observable

projects

releases

users

action

• action(
      operations: Action | Action[],
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Perform action operations against the configured dataset Returns a promise that resolves to the transaction result

  Parameters

  • operations: Action | Action[]

    Action operation(s) to execute
  • Optionaloptions: BaseActionOptions

    Action options

  Returns Promise<SingleActionResult | MultipleActionResult>

clone

• clone(): SanityClient

  Clone the client - returns a new instance

  Returns SanityClient

config

• config(): InitializedClientConfig

  Returns the current client configuration

  Returns InitializedClientConfig
• config(newConfig?: Partial<ClientConfig>): this

  Reconfigure the client. Note that this mutates the current client.

  Parameters

  • OptionalnewConfig: Partial<ClientConfig>

  Returns this

create

• create<R extends Record<string, any> = Record<string, any>>(
      document: SanityDocumentStub<R>,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document. Requires a _type property. If no _id is provided, it will be generated by the database. Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: SanityDocumentStub<R>

    Document to create
  • options: FirstDocumentMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>
• create<R extends Record<string, any> = Record<string, any>>(
      document: SanityDocumentStub<R>,
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Create a document. Requires a _type property. If no _id is provided, it will be generated by the database. Returns a promise that resolves to an array containing the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: SanityDocumentStub<R>

    Document to create
  • options: AllDocumentsMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>[]>
• create<R extends Record<string, any> = Record<string, any>>(
      document: SanityDocumentStub<R>,
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Create a document. Requires a _type property. If no _id is provided, it will be generated by the database. Returns a promise that resolves to a mutation result object containing the ID of the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: SanityDocumentStub<R>

    Document to create
  • options: FirstDocumentIdMutationOptions

    Mutation options

  Returns Promise<SingleMutationResult>
• create<R extends Record<string, any> = Record<string, any>>(
      document: SanityDocumentStub<R>,
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Create a document. Requires a _type property. If no _id is provided, it will be generated by the database. Returns a promise that resolves to a mutation result object containing the ID of the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: SanityDocumentStub<R>

    Document to create
  • options: AllDocumentIdsMutationOptions

    Mutation options

  Returns Promise<MultipleMutationResult>
• create<R extends Record<string, any> = Record<string, any>>(
      document: SanityDocumentStub<R>,
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document. Requires a _type property. If no _id is provided, it will be generated by the database. Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: SanityDocumentStub<R>

    Document to create
  • Optionaloptions: BaseMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>

createIfNotExists

• createIfNotExists<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document if no document with the same ID already exists. Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to create
  • options: FirstDocumentMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>
• createIfNotExists<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Create a document if no document with the same ID already exists. Returns a promise that resolves to an array containing the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to create
  • options: AllDocumentsMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>[]>
• createIfNotExists<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Create a document if no document with the same ID already exists. Returns a promise that resolves to a mutation result object containing the ID of the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to create
  • options: FirstDocumentIdMutationOptions

    Mutation options

  Returns Promise<SingleMutationResult>
• createIfNotExists<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Create a document if no document with the same ID already exists. Returns a promise that resolves to a mutation result object containing the ID of the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to create
  • options: AllDocumentIdsMutationOptions

    Mutation options

  Returns Promise<MultipleMutationResult>
• createIfNotExists<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document if no document with the same ID already exists. Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to create
  • Optionaloptions: BaseMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>

createOrReplace

• createOrReplace<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document if it does not exist, or replace a document with the same document ID Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to either create or replace
  • options: FirstDocumentMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>
• createOrReplace<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Create a document if it does not exist, or replace a document with the same document ID Returns a promise that resolves to an array containing the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to either create or replace
  • options: AllDocumentsMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>[]>
• createOrReplace<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Create a document if it does not exist, or replace a document with the same document ID Returns a promise that resolves to a mutation result object containing the ID of the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to either create or replace
  • options: FirstDocumentIdMutationOptions

    Mutation options

  Returns Promise<SingleMutationResult>
• createOrReplace<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Create a document if it does not exist, or replace a document with the same document ID Returns a promise that resolves to a mutation result object containing the created document ID.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to either create or replace
  • options: AllDocumentIdsMutationOptions

    Mutation options

  Returns Promise<MultipleMutationResult>
• createOrReplace<R extends Record<string, any> = Record<string, any>>(
      document: IdentifiedSanityDocumentStub<R>,
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Create a document if it does not exist, or replace a document with the same document ID Returns a promise that resolves to the created document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • document: IdentifiedSanityDocumentStub<R>

    Document to either create or replace
  • Optionaloptions: BaseMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>

delete

• delete<R extends Record<string, any> = Record<string, any>>(
      id: string,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Deletes a document with the given document ID. Returns a promise that resolves to the deleted document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • id: string

    Document ID to delete
  • options: FirstDocumentMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>>
• delete<R extends Record<string, any> = Record<string, any>>(
      id: string,
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Deletes a document with the given document ID. Returns a promise that resolves to an array containing the deleted document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • id: string

    Document ID to delete
  • options: AllDocumentsMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>[]>
• delete(
      id: string,
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Deletes a document with the given document ID. Returns a promise that resolves to a mutation result object containing the deleted document ID.

  Parameters

  • id: string

    Document ID to delete
  • options: FirstDocumentIdMutationOptions

    Options for the mutation

  Returns Promise<SingleMutationResult>
• delete(
      id: string,
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Deletes a document with the given document ID. Returns a promise that resolves to a mutation result object containing the deleted document ID.

  Parameters

  • id: string

    Document ID to delete
  • options: AllDocumentIdsMutationOptions

    Options for the mutation

  Returns Promise<MultipleMutationResult>
• delete<R extends Record<string, any> = Record<string, any>>(
      id: string,
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Deletes a document with the given document ID. Returns a promise that resolves to the deleted document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • id: string

    Document ID to delete
  • Optionaloptions: BaseMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>>
• delete<R extends Record<string, any> = Record<string, any>>(
      selection: MutationSelection,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Deletes one or more documents matching the given query or document ID. Returns a promise that resolves to first deleted document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • selection: MutationSelection

    An object with either an id or query key defining what to delete
  • options: FirstDocumentMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>>
• delete<R extends Record<string, any> = Record<string, any>>(
      selection: MutationSelection,
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Deletes one or more documents matching the given query or document ID. Returns a promise that resolves to an array containing the deleted documents.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • selection: MutationSelection

    An object with either an id or query key defining what to delete
  • options: AllDocumentsMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>[]>
• delete(
      selection: MutationSelection,
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Deletes one or more documents matching the given query or document ID. Returns a promise that resolves to a mutation result object containing the ID of the first deleted document.

  Parameters

  • selection: MutationSelection

    An object with either an id or query key defining what to delete
  • options: FirstDocumentIdMutationOptions

    Options for the mutation

  Returns Promise<SingleMutationResult>
• delete(
      selection: MutationSelection,
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Deletes one or more documents matching the given query or document ID. Returns a promise that resolves to a mutation result object containing the document IDs that were deleted.

  Parameters

  • selection: MutationSelection

    An object with either an id or query key defining what to delete
  • options: AllDocumentIdsMutationOptions

    Options for the mutation

  Returns Promise<MultipleMutationResult>
• delete<R extends Record<string, any> = Record<string, any>>(
      selection: MutationSelection,
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Deletes one or more documents matching the given query or document ID. Returns a promise that resolves to first deleted document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • selection: MutationSelection

    An object with either an id or query key defining what to delete
  • Optionaloptions: BaseMutationOptions

    Options for the mutation

  Returns Promise<SanityDocument<R>>

discardVersion

• discardVersion(
      params: { publishedId: string; releaseId?: string },
      purge?: boolean,
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Deletes the draft or release version of a document.

  Parameters

  • params: { publishedId: string; releaseId?: string }

    Version action parameters:

    • releaseId - The ID of the release to discard the document from.
    • publishedId - The published ID of the document to discard.
  • Optionalpurge: boolean

    if true the document history is also discarded.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  a promise that resolves to the transactionId.

  Remarks

  • Discarding a version with no releaseId will discard the draft version of the published document.
  • If the draft or release version does not exist, any error will throw.

  Example: Discarding a release version of a document

  client.discardVersion({publishedId: 'myDocument', releaseId: 'myRelease'})
  // The document with the ID `versions.myRelease.myDocument` will be discarded.
  Copy

  Example: Discarding a draft version of a document

  client.discardVersion({publishedId: 'myDocument'})
  // The document with the ID `drafts.myDocument` will be discarded.
  Copy

fetch

• fetch<
      R = any,
      Q extends QueryWithoutParams = QueryWithoutParams,
      const G extends string = string,
  >(
      query: G,
      params?: QueryWithoutParams | Q,
  ): Promise<ClientReturn<G, R>>

  Perform a GROQ-query against the configured dataset.

  Type Parameters

  • R = any
  • Q extends QueryWithoutParams = QueryWithoutParams
  • const G extends string = string

  Parameters

  • query: G

    GROQ-query to perform
  • Optionalparams: QueryWithoutParams | Q

  Returns Promise<ClientReturn<G, R>>
• fetch<
      R = any,
      Q extends QueryParams | QueryWithoutParams = QueryParams,
      const G extends string = string,
  >(
      query: G,
      params: Q extends QueryWithoutParams ? QueryWithoutParams : Q,
      options?: FilteredResponseQueryOptions,
  ): Promise<ClientReturn<G, R>>

  Perform a GROQ-query against the configured dataset.

  Type Parameters

  • R = any
  • Q extends QueryParams | QueryWithoutParams = QueryParams
  • const G extends string = string

  Parameters

  • query: G

    GROQ-query to perform
  • params: Q extends QueryWithoutParams ? QueryWithoutParams : Q

    Optional query parameters
  • Optionaloptions: FilteredResponseQueryOptions

    Optional request options

  Returns Promise<ClientReturn<G, R>>
• fetch<
      R = any,
      Q extends QueryParams | QueryWithoutParams = QueryParams,
      const G extends string = string,
  >(
      query: G,
      params: Q extends QueryWithoutParams ? QueryWithoutParams : Q,
      options: UnfilteredResponseQueryOptions,
  ): Promise<RawQueryResponse<ClientReturn<G, R>>>

  Perform a GROQ-query against the configured dataset.

  Type Parameters

  • R = any
  • Q extends QueryParams | QueryWithoutParams = QueryParams
  • const G extends string = string

  Parameters

  • query: G

    GROQ-query to perform
  • params: Q extends QueryWithoutParams ? QueryWithoutParams : Q

    Optional query parameters
  • options: UnfilteredResponseQueryOptions

    Request options

  Returns Promise<RawQueryResponse<ClientReturn<G, R>>>
• fetch<
      R = any,
      Q extends QueryParams | QueryWithoutParams = QueryParams,
      const G extends string = string,
  >(
      query: G,
      params: Q extends QueryWithoutParams ? QueryWithoutParams : Q,
      options: UnfilteredResponseWithoutQuery,
  ): Promise<RawQuerylessQueryResponse<ClientReturn<G, R>>>

  Perform a GROQ-query against the configured dataset.

  Type Parameters

  • R = any
  • Q extends QueryParams | QueryWithoutParams = QueryParams
  • const G extends string = string

  Parameters

  • query: G

    GROQ-query to perform
  • params: Q extends QueryWithoutParams ? QueryWithoutParams : Q

    Optional query parameters
  • options: UnfilteredResponseWithoutQuery

    Request options

  Returns Promise<RawQuerylessQueryResponse<ClientReturn<G, R>>>

getDataUrl

• getDataUrl(operation: string, path?: string): string

  Get a Sanity API URL for the data operation and path provided

  Parameters

  • operation: string

    Data operation (eg query, mutate, listen or similar)
  • Optionalpath: string

    Path to append after the operation

  Returns string

getDocument

• getDocument<R extends Record<string, any> = Record<string, any>>(
      id: string,
      options?: { releaseId?: string; signal?: AbortSignal; tag?: string },
  ): Promise<undefined | SanityDocument<R>>

  Fetch a single document with the given ID.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • id: string

    Document ID to fetch
  • Optionaloptions: { releaseId?: string; signal?: AbortSignal; tag?: string }

    Request options

  Returns Promise<undefined | SanityDocument<R>>

getDocuments

• getDocuments<R extends Record<string, any> = Record<string, any>>(
      ids: string[],
      options?: { signal?: AbortSignal; tag?: string },
  ): Promise<(null | SanityDocument<R>)[]>

  Fetch multiple documents in one request. Should be used sparingly - performing a query is usually a better option. The order/position of documents is preserved based on the original array of IDs. If any of the documents are missing, they will be replaced by a null entry in the returned array

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • ids: string[]

    Document IDs to fetch
  • Optionaloptions: { signal?: AbortSignal; tag?: string }

    Request options

  Returns Promise<(null | SanityDocument<R>)[]>

getUrl

• getUrl(uri: string, canUseCdn?: boolean): string

  Get a Sanity API URL for the URI provided

  Parameters

  • uri: string

    URI/path to build URL for
  • OptionalcanUseCdn: boolean

    Whether or not to allow using the API CDN for this route

  Returns string

mutate

• mutate<R extends Record<string, any> = Record<string, any>>(
      operations: Patch | Mutation<R>[] | Transaction,
      options: FirstDocumentMutationOptions,
  ): Promise<SanityDocument<R>>

  Perform mutation operations against the configured dataset Returns a promise that resolves to the first mutated document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • operations: Patch | Mutation<R>[] | Transaction

    Mutation operations to execute
  • options: FirstDocumentMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>
• mutate<R extends Record<string, any> = Record<string, any>>(
      operations: Patch | Transaction | Mutation<R>[],
      options: AllDocumentsMutationOptions,
  ): Promise<SanityDocument<R>[]>

  Perform mutation operations against the configured dataset. Returns a promise that resolves to an array of the mutated documents.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • operations: Patch | Transaction | Mutation<R>[]

    Mutation operations to execute
  • options: AllDocumentsMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>[]>
• mutate<R extends Record<string, any> = Record<string, any>>(
      operations: Patch | Transaction | Mutation<R>[],
      options: FirstDocumentIdMutationOptions,
  ): Promise<SingleMutationResult>

  Perform mutation operations against the configured dataset Returns a promise that resolves to a mutation result object containing the document ID of the first mutated document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • operations: Patch | Transaction | Mutation<R>[]

    Mutation operations to execute
  • options: FirstDocumentIdMutationOptions

    Mutation options

  Returns Promise<SingleMutationResult>
• mutate<R extends Record<string, any> = Record<string, any>>(
      operations: Patch | Transaction | Mutation<R>[],
      options: AllDocumentIdsMutationOptions,
  ): Promise<MultipleMutationResult>

  Perform mutation operations against the configured dataset Returns a promise that resolves to a mutation result object containing the mutated document IDs.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • operations: Patch | Transaction | Mutation<R>[]

    Mutation operations to execute
  • options: AllDocumentIdsMutationOptions

    Mutation options

  Returns Promise<MultipleMutationResult>
• mutate<R extends Record<string, any> = Record<string, any>>(
      operations: Patch | Transaction | Mutation<R>[],
      options?: BaseMutationOptions,
  ): Promise<SanityDocument<R>>

  Perform mutation operations against the configured dataset Returns a promise that resolves to the first mutated document.

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • operations: Patch | Transaction | Mutation<R>[]

    Mutation operations to execute
  • Optionaloptions: BaseMutationOptions

    Mutation options

  Returns Promise<SanityDocument<R>>

patch

• patch(documentId: string, operations?: PatchOperations): Patch

  Create a new buildable patch of operations to perform

  Parameters

  • documentId: string

    Document ID to patch
  • Optionaloperations: PatchOperations

    Optional object of patch operations to initialize the patch instance with

  Returns Patch

  Patch instance - call .commit() to perform the operations defined
• patch(documentIds: string[], operations?: PatchOperations): Patch

  Create a new buildable patch of operations to perform

  Parameters

  • documentIds: string[]

    Array of document IDs to patch
  • Optionaloperations: PatchOperations

    Optional object of patch operations to initialize the patch instance with

  Returns Patch

  Patch instance - call .commit() to perform the operations defined
• patch(selection: MutationSelection, operations?: PatchOperations): Patch

  Create a new buildable patch of operations to perform

  Parameters

  • selection: MutationSelection

    An object with query and optional params, defining which document(s) to patch
  • Optionaloperations: PatchOperations

    Optional object of patch operations to initialize the patch instance with

  Returns Patch

  Patch instance - call .commit() to perform the operations defined

replaceVersion

• replaceVersion<R extends Record<string, any>>(
      args: {
          document: SanityDocumentStub<R>;
          publishedId: string;
          releaseId?: string;
      },
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Replaces an existing version document.

  Type Parameters

  • R extends Record<string, any>

  Parameters

  • args: { document: SanityDocumentStub<R>; publishedId: string; releaseId?: string }

    Version action parameters:

    • document - The new document to replace the version with.
    • releaseId - The ID of the release where the document version is replaced.
    • publishedId - The ID of the published document to replace.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  a promise that resolves to the transactionId.

  Remarks

  • Requires a document with a _type property.
  • If the document._id is defined, it should be a draft or release version ID that matches the version ID generated from publishedId and releaseId.
  • If the document._id is not defined, it will be generated from publishedId and releaseId.
  • Replacing a version with no releaseId will replace the draft version of the published document.
  • At least one of the version or published documents must exist.

  Example: Replacing a release version of a published document with a generated version ID

  await client.replaceVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
    releaseId: 'myRelease',
  })
  
  // The following document will be patched:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Replacing a release version of a published document with a specified version ID

  await client.replaceVersion({
    document: {_type: 'myDocument', _id: 'versions.myRelease.myDocument', title: 'My Document'},
    // `publishedId` and `releaseId` are not required since `document._id` has been specified
  })
  
  // The following document will be patched:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Replacing a draft version of a published document

  await client.replaceVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
  })
  
  // The following document will be patched:
  // {
  //   _id: 'drafts.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

• replaceVersion<R extends Record<string, any>>(
      args: {
          document: IdentifiedSanityDocumentStub<R>;
          publishedId?: string;
          releaseId?: string;
      },
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Replaces an existing version document.

  Type Parameters

  • R extends Record<string, any>

  Parameters

  • args: {
        document: IdentifiedSanityDocumentStub<R>;
        publishedId?: string;
        releaseId?: string;
    }

    Version action parameters:

    • document - The new document to replace the version with.
    • releaseId - The ID of the release where the document version is replaced.
    • publishedId - The ID of the published document to replace.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  a promise that resolves to the transactionId.

  Remarks

  • Requires a document with a _type property.
  • If the document._id is defined, it should be a draft or release version ID that matches the version ID generated from publishedId and releaseId.
  • If the document._id is not defined, it will be generated from publishedId and releaseId.
  • Replacing a version with no releaseId will replace the draft version of the published document.
  • At least one of the version or published documents must exist.

  Example: Replacing a release version of a published document with a generated version ID

  await client.replaceVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
    releaseId: 'myRelease',
  })
  
  // The following document will be patched:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Replacing a release version of a published document with a specified version ID

  await client.replaceVersion({
    document: {_type: 'myDocument', _id: 'versions.myRelease.myDocument', title: 'My Document'},
    // `publishedId` and `releaseId` are not required since `document._id` has been specified
  })
  
  // The following document will be patched:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Replacing a draft version of a published document

  await client.replaceVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
  })
  
  // The following document will be patched:
  // {
  //   _id: 'drafts.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

request

• request<R = any>(options: RawRequestOptions): Promise<R>

  Perform a request against the Sanity API NOTE: Only use this for Sanity API endpoints, not for your own APIs!

  Type Parameters

  • R = any

  Parameters

  • options: RawRequestOptions

    Request options

  Returns Promise<R>

  Promise resolving to the response body

transaction

• transaction<R extends Record<string, any> = Record<string, any>>(
      operations?: Mutation<R>[],
  ): Transaction

  Create a new transaction of mutations

  Type Parameters

  • R extends Record<string, any> = Record<string, any>

  Parameters

  • Optionaloperations: Mutation<R>[]

    Optional array of mutation operations to initialize the transaction instance with

  Returns Transaction

unpublishVersion

• unpublishVersion(
      params: { publishedId: string; releaseId: string },
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Used to indicate when a document within a release should be unpublished when the release is run.

  Parameters

  • params: { publishedId: string; releaseId: string }

    Version action parameters:

    • releaseId - The ID of the release to unpublish the document from.
    • publishedId - The published ID of the document to unpublish.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  a promise that resolves to the transactionId.

  Remarks

  • If the published document does not exist, an error will be thrown.

  Example: Unpublishing a release version of a published document

  await client.unpublishVersion({publishedId: 'myDocument', releaseId: 'myRelease'})
  // The document with the ID `versions.myRelease.myDocument` will be unpublished. when `myRelease` is run.
  Copy

withConfig

• withConfig(newConfig?: Partial<ClientConfig>): SanityClient

  Clone the client with a new (partial) configuration.

  Parameters

  • OptionalnewConfig: Partial<ClientConfig>

    New client configuration properties, shallowly merged with existing configuration

  Returns SanityClient

createVersion

• createVersion<R extends Record<string, any>>(
      args: {
          document: SanityDocumentStub<R>;
          publishedId: string;
          releaseId?: string;
      },
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Creates a new version of a published document.

  Type Parameters

  • R extends Record<string, any>

  Parameters

  • args: { document: SanityDocumentStub<R>; publishedId: string; releaseId?: string }

    Version action parameters:

    • document - The document to create as a new version (must include _type).
    • publishedId - The ID of the published document being versioned.
    • releaseId - The ID of the release to create the version for.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  A promise that resolves to the transactionId.

  Remarks

  • Requires a document with a _type property.
  • Creating a version with no releaseId will create a new draft version of the published document.
  • If the document._id is defined, it should be a draft or release version ID that matches the version ID generated from publishedId and releaseId.
  • If the document._id is not defined, it will be generated from publishedId and releaseId.
  • To create a version of an unpublished document, use the client.create method.

  Example: Creating a new version of a published document with a generated version ID

  const transactionId = await client.createVersion({
    // The document does not need to include an `_id` property since it will be generated from `publishedId` and `releaseId`
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
    releaseId: 'myRelease',
  })
  
  // The following document will be created:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Creating a new version of a published document with a specified version ID

  const transactionId = await client.createVersion({
    document: {_type: 'myDocument', _id: 'versions.myRelease.myDocument', title: 'My Document'},
    // `publishedId` and `releaseId` are not required since `document._id` has been specified
  })
  
  // The following document will be created:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Creating a new draft version of a published document

  const transactionId = await client.createVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
  })
  
  // The following document will be created:
  // {
  //   _id: 'drafts.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

• createVersion<R extends Record<string, any>>(
      args: {
          document: IdentifiedSanityDocumentStub<R>;
          publishedId?: string;
          releaseId?: string;
      },
      options?: BaseActionOptions,
  ): Promise<SingleActionResult | MultipleActionResult>

  Creates a new version of a published document.

  Type Parameters

  • R extends Record<string, any>

  Parameters

  • args: {
        document: IdentifiedSanityDocumentStub<R>;
        publishedId?: string;
        releaseId?: string;
    }

    Version action parameters:

    • document - The document to create as a new version (must include _type).
    • publishedId - The ID of the published document being versioned.
    • releaseId - The ID of the release to create the version for.
  • Optionaloptions: BaseActionOptions

    Additional action options.

  Returns Promise<SingleActionResult | MultipleActionResult>

  A promise that resolves to the transactionId.

  Remarks

  • Requires a document with a _type property.
  • Creating a version with no releaseId will create a new draft version of the published document.
  • If the document._id is defined, it should be a draft or release version ID that matches the version ID generated from publishedId and releaseId.
  • If the document._id is not defined, it will be generated from publishedId and releaseId.
  • To create a version of an unpublished document, use the client.create method.

  Example: Creating a new version of a published document with a generated version ID

  const transactionId = await client.createVersion({
    // The document does not need to include an `_id` property since it will be generated from `publishedId` and `releaseId`
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
    releaseId: 'myRelease',
  })
  
  // The following document will be created:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Creating a new version of a published document with a specified version ID

  const transactionId = await client.createVersion({
    document: {_type: 'myDocument', _id: 'versions.myRelease.myDocument', title: 'My Document'},
    // `publishedId` and `releaseId` are not required since `document._id` has been specified
  })
  
  // The following document will be created:
  // {
  //   _id: 'versions.myRelease.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy

  Example: Creating a new draft version of a published document

  const transactionId = await client.createVersion({
    document: {_type: 'myDocument', title: 'My Document'},
    publishedId: 'myDocument',
  })
  
  // The following document will be created:
  // {
  //   _id: 'drafts.myDocument',
  //   _type: 'myDocument',
  //   title: 'My Document',
  // }
  Copy