[5.x] Support query scopes in REST API

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}

src/API/FilterAuthorizer.php

@@ -6,6 +6,8 @@
 
 class FilterAuthorizer extends AbstractAuthorizer
 {
+ protected $configKey = 'allowed_filters';
+
  /**
  * Get allowed filters for resource.
  *
@@ -17,7 +19,7 @@ class FilterAuthorizer extends AbstractAuthorizer
  */
  public function allowedForResource($configFile, $queriedResource)
  {
- $config = config("statamic.{$configFile}.resources.{$queriedResource}.allowed_filters");
+ $config = config("statamic.{$configFile}.resources.{$queriedResource}.{$this->configKey}");
 
  // Use explicitly configured `allowed_filters` array, otherwise no filters should be allowed.
  return is_array($config)
@@ -54,7 +56,7 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
 
  // Determine if any of our queried resources have filters explicitly disabled.
  $disabled = $resources
- ->filter(fn ($resource) => Arr::get($config, "{$resource}.allowed_filters") === false)
+ ->filter(fn ($resource) => Arr::get($config, "{$resource}.{$this->configKey}") === false)
  ->isNotEmpty();
 
  // If any queried resource is explicitly disabled, then no filters should be allowed.
@@ -65,10 +67,10 @@ public function allowedForSubResources($configFile, $queriedResource, $queriedHa
  // Determine `allowed_filters` by filtering out any that don't appear in all of them.
  // A resource named `*` will apply to all enabled resources at once.
  return $resources
- ->map(fn ($resource) => $config[$resource]['allowed_filters'] ?? [])
+ ->map(fn ($resource) => $config[$resource][$this->configKey] ?? [])
  ->reduce(function ($carry, $allowedFilters) use ($config) {
- return $carry->intersect($allowedFilters)->merge($config['*']['allowed_filters'] ?? []);
- }, collect($config[$resources[0] ?? '']['allowed_filters'] ?? []))
+ return $carry->intersect($allowedFilters)->merge($config['*'][$this->configKey] ?? []);
+ }, collect($config[$resources[0] ?? ''][$this->configKey] ?? []))
  ->all();
  }
 }

src/API/QueryScopeAuthorizer.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace Statamic\API;
+
+class QueryScopeAuthorizer extends FilterAuthorizer
+{
+ protected $configKey = 'allowed_query_scopes';
+}

src/Http/Controllers/API/ApiController.php

@@ -5,8 +5,10 @@
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\ApiValidationException;
 use Statamic\Exceptions\NotFoundHttpException;
+use Statamic\Facades\Scope;
 use Statamic\Facades\Site;
 use Statamic\Http\Controllers\Controller;
+use Statamic\Support\Arr;
 use Statamic\Support\Str;
 use Statamic\Tags\Concerns\QueriesConditions;
 
@@ -80,12 +82,26 @@ protected function filterAllowedResources($items)
  *
  * @param \Statamic\Query\Builder $query
  * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ *
+ * @deprecated
  */
  protected function filterSortAndPaginate($query)
+ {
+ return $this->updateAndPaginate($query);
+ }
+
+ /**
+ * Filter, sort, scope, and paginate query for API resource output.
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return \Statamic\Extensions\Pagination\LengthAwarePaginator
+ */
+ protected function updateAndPaginate($query)
  {
  return $this
  ->filter($query)
  ->sort($query)
+ ->scope($query)
  ->paginate($query);
  }
 
@@ -171,6 +187,52 @@ protected function doesntHaveFilter($field)
  ->contains($field);
  }
 
+ /**
+ * Apply query scopes a query based on conditions in the query_scope parameter.
+ *
+ * /endpoint?query_scope[scope_handle]=foo&query_scope[another_scope]=bar
+ *
+ * @param \Statamic\Query\Builder $query
+ * @return $this
+ */
+ protected function scope($query)
+ {
+ $this->getScopes()
+ ->each(function ($value, $handle) use ($query) {
+ Scope::find($handle)?->apply($query, Arr::wrap($value));
+ });
+
+ return $this;
+ }
+
+ /**
+ * Get scopes for querying.
+ *
+ * @return \Illuminate\Support\Collection
+ */
+ protected function getScopes()
+ {
+ if (! method_exists($this, 'allowedQueryScopes')) {
+ return collect();
+ }
+
+ $scopes = collect(request()->query_scope ?? []);
+
+ $allowedScopes = collect($this->allowedQueryScopes());
+
+ $forbidden = $scopes
+ ->keys()
+ ->filter(fn ($handle) => ! Scope::find($handle) || ! $allowedScopes->contains($handle));
+
+ if ($forbidden->isNotEmpty()) {
+ throw ApiValidationException::withMessages([
+ 'query_scope' => Str::plural('Forbidden query scope', $forbidden).': '.$forbidden->join(', '),
+ ]);
+ }
+
+ return $scopes;
+ }
+
  /**
  * Sorts the query based on the sort parameter.
  *

src/Http/Controllers/API/AssetsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Http\Resources\API\AssetResource;
 
 class AssetsController extends ApiController
@@ -22,7 +23,7 @@ public function index($assetContainer)
  ->filter->isRelationship()->keys()->all();
 
  return app(AssetResource::class)::collection(
- $this->filterSortAndPaginate($assetContainer->queryAssets()->with($with))
+ $this->updateAndPaginate($assetContainer->queryAssets()->with($with))
  );
  }
 
@@ -37,4 +38,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'assets', $this->containerHandle);
+ }
 }

src/Http/Controllers/API/CollectionEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Entry;
 use Statamic\Http\Resources\API\EntryResource;
@@ -29,7 +30,7 @@ public function index($collection)
  ->filter->isRelationship()->keys()->all();
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($collection->queryEntries()->with($with))
+ $this->updateAndPaginate($collection->queryEntries()->with($with))
  );
  }
 
@@ -81,4 +82,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/CollectionTreeController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Http\Resources\API\TreeResource;
 use Statamic\Query\ItemQueryBuilder;
@@ -48,4 +49,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->collectionHandle);
+ }
 }

src/Http/Controllers/API/TaxonomyTermEntriesController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Facades\Statamic\API\ResourceAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Collection;
@@ -46,7 +47,7 @@ public function index($taxonomy, $term)
  $with = $this->getRelationshipFieldsFromCollections($taxonomy);
 
  return app(EntryResource::class)::collection(
- $this->filterSortAndPaginate($query->with($with))
+ $this->updateAndPaginate($query->with($with))
  );
  }
 
@@ -72,4 +73,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'collections', $this->allowedCollections);
+ }
 }

src/Http/Controllers/API/TaxonomyTermsController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\Term;
 use Statamic\Http\Resources\API\TermResource;
@@ -24,7 +25,7 @@ public function index($taxonomy)
  ->filter->isRelationship()->keys()->all();
 
  return app(TermResource::class)::collection(
- $this->filterSortAndPaginate($taxonomy->queryTerms()->with($with))
+ $this->updateAndPaginate($taxonomy->queryTerms()->with($with))
  );
  }
 
@@ -43,4 +44,9 @@ protected function allowedFilters()
  {
  return FilterAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForSubResources('api', 'taxonomies', $this->taxonomyHandle);
+ }
 }

src/Http/Controllers/API/UsersController.php

@@ -3,6 +3,7 @@
 namespace Statamic\Http\Controllers\API;
 
 use Facades\Statamic\API\FilterAuthorizer;
+use Facades\Statamic\API\QueryScopeAuthorizer;
 use Statamic\Exceptions\NotFoundHttpException;
 use Statamic\Facades\User;
 use Statamic\Http\Resources\API\UserResource;
@@ -16,7 +17,7 @@ public function index()
  $this->abortIfDisabled();
 
  return app(UserResource::class)::collection(
- $this->filterSortAndPaginate(User::query())
+ $this->updateAndPaginate(User::query())
  );
  }
 
@@ -42,4 +43,9 @@ protected function allowedFilters()
  ->reject(fn ($field) => in_array($field, ['password', 'password_hash']))
  ->all();
  }
+
+ protected function allowedQueryScopes()
+ {
+ return QueryScopeAuthorizer::allowedForResource('api', 'users');
+ }
 }

tests/API/APITest.php

@@ -10,6 +10,7 @@
 use Statamic\Facades\Blueprint;
 use Statamic\Facades\Token;
 use Statamic\Facades\User;
+use Statamic\Query\Scopes\Scope;
 use Tests\PreventSavingStacheItemsToDisk;
 use Tests\TestCase;
 
@@ -136,6 +137,25 @@ public function it_filters_out_past_entries_from_past_private_collection()
  $response->assertJsonPath('data.0.id', 'a');
  }
 
+ #[Test]
+ public function it_can_use_a_query_scope_on_collection_entries_when_configuration_allows_for_it()
+ {
+ app('statamic.scopes')['test_scope'] = TestScope::class;
+
+ Facades\Config::set('statamic.api.resources.collections.pages', [
+ 'allowed_query_scopes' => ['test_scope'],
+ ]);
+
+ Facades\Collection::make('pages')->save();
+
+ Facades\Entry::make()->collection('pages')->id('about')->slug('about')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('dance')->slug('dance')->published(true)->save();
+ Facades\Entry::make()->collection('pages')->id('nectar')->slug('nectar')->published(true)->save();
+
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=is&query_scope[test_scope][value]=about', 1);
+ $this->assertEndpointDataCount('/api/collections/pages/entries?query_scope[test_scope][operator]=isnt&query_scope[test_scope][value]=about', 2);
+ }
+
  #[Test]
  public function it_can_filter_collection_entries_when_configuration_allows_for_it()
  {
@@ -592,3 +612,11 @@ public function handle(\Statamic\Contracts\Tokens\Token $token, \Illuminate\Http
  return $next($token);
  }
 }
+
+class TestScope extends Scope
+{
+ public function apply($query, $values)
+ {
+ $query->where('id', $values['operator'] == 'is' ? '=' : '!=', $values['value']);
+ }
+}