Calling the API

Every route in the API reference is a method on one of the facade’s accessors: pages(), blogPosts(), faqItems(), fetchskiMedia() and so on. A call is one line.

use Fetchski\AttractCmsLaravel\Facades\Attract;

$post = Attract::blogPosts()->getBlog(id: $id);
$entries = Attract::formSubmissions()->listFormSubmissions(formId: $formId); // needs forms:read
$images = Attract::fetchskiMedia()->listMediaImages(q: 'beach');            // needs images:read

The default site
Another site
Injected

Attract::blogPosts() reaches the site FETCHSKI_ATTRACT_SITE names.

$site = Attract::site('globex');
$faqs = $site->faqItems()->listFaqItems(perPage: 20);

The facade reaches AttractManager; inject it where you prefer:

use Fetchski\AttractCmsLaravel\AttractManager;

public function __construct(private readonly AttractManager $attract) {}

$post = $this->attract->blogPosts()->getBlog(id: $id);

Print every method of an accessor with its route:

Terminal

php artisan attract:list blogPosts

Try one on the real site:

Terminal

php artisan attract:call blogPosts.listBlogs perPage=5

Arguments

Named and typed

listBlogs(perPage: 20, search: 'launch'). Your editor completes them.

A body is arguments too

updateTestimonial(id: $id, quote: 'Great service', rating: 5): no model to build.

null is not sent

A PATCH changes only what you name, so nothing else is touched.

Laravel's own values

Carbon or a string for a date, a PHP enum or its value, $request->file() for a file.

Answers

Answers are readonly objects with properties, never getters.

$post = Attract::blogPosts()->getBlog(id: $id);

$post->title;          // string: always sent, so never null
$post->publishedAt;    // CarbonImmutable
$post->category;       // ?Collection
$post->toArray();      // the site's JSON

What each type becomes

A field the site always sends is non-nullable. Lists are Collections. Date-times and Unix times are CarbonImmutable. Nested objects are their own classes, under Fetchski\AttractCmsLaravel\Data.

Enums stay open

A known value is a PHP enum case; a value a newer site adds stays its string, so an older SDK never breaks on it.

Answered, not required to write

Some models are both an answer and a body. A field the site always sends (a testimonial’s slug, visibility, archived) is non-null when it answers, yet stays an optional argument when you write: updateTestimonial(id: $id, quote: '…') leaves the others alone.

Every answer is checked

Against its type, before your code sees it. A value of the wrong type is an error naming the field, never coerced.

Whole lists, missing documents, jobs

Attract::faqItems()->listFaqItemsAll(perPage: 50)
    ->each(fn ($item) => logger()->info($item->title));

$post = Attract::blogPosts()->findBlog(id: $id);   // ?Blog

$job = Attract::site('acme')->blogPosts()->archiveBlogs(ids: $ids)->wait();

…All() returns a LazyCollection that fetches a page at a time as you iterate: see Paging.
find…() sits beside each get…(): only a 404 becomes null.
A job’s wait() needs the job route, which only the management key reaches: on an API key it throws SiteConfigurationError naming the job id.

What an API key reaches

Content
Feature routes
Drafts and publishing
Never

Every content type, with that type’s scopes: content:<type>:read lists and reads the published documents, :write creates and changes drafts (and reads them), :publish takes them live, and :delete deletes. Pages, the media libraries and Site settings (global:*) included. Each method’s reference page names its scope under Access; Required scopes lists them all.

Importing blog posts (with their images and videos), recording conversions, and reading fetchskiMedia() images and videos, form submissions, conversions and analytics: each with the scope its page names.

On a type with drafts, a create or update in published mode (the default) also takes the document live, so the key needs the type’s publish scope too. Pass aposMode: 'draft' to change only the draft, then publish it with a key that may. A type without drafts (redirects, photo feeds, the media folders) needs only its write scope.

Ids

A document’s id names its locale and mode: <document id>:<locale>:<mode>.

A create answers the id of its mode

Published by default (…:en:published); aposMode: 'draft' makes only a draft (…:en:draft).

Reads take either id

Or the bare document id.

Deleting takes the draft id

It removes both copies. The draft id is the published id with the last part changed.

An empty or blank id is refused before anything is sent, as a RequestNotSent: it would otherwise call another route (an empty getBlog id would read the whole list).

Uploads

Pass the file the request brought, as it is. It goes under the name it was uploaded with, as the site reads a file’s type from its extension:

$site->attachments()->uploadAttachment(file: $request->file('photo'));

uploadAttachment() needs the write scope of a media type (content:images:write, content:files:write or content:videos:write).

An upload is signed like any write: a key with a signing secret signs it by its SHA-256, which means reading the file twice (hashed, then sent). An UploadedFile, a path or an SplFileObject all can; a one-pass stream is sent unsigned, or refused when the key’s api_signing mode signs writes.

A signed upload signs its SHA-256. A multipart body isn’t signed byte for byte: the request declares the hex SHA-256 of the exact body in X-Fetchski-Content-SHA256 and signs that digest in the body’s place. The site checks the signature before it reads the upload, then the bytes against the digest, and stores nothing that doesn’t match. The SDKs do this for you; Signing requests shows it by hand.

Timeouts

Slow routes set their own

Each FetchskiAI route, and the blog import with images, carries its own timeout: the site’s 600-second cap per AI call plus 15 seconds. You never pass one per call.

The larger one wins

The client’s timeout (15 seconds by default) covers every other route. Raise it, and every call gets at least that long.

.env

FETCHSKI_ATTRACT_TIMEOUT=60   # seconds per attempt, for every route that has no longer one

A route without a method

Every route the site documents has a method, but request() calls any route exactly as the methods do: the key, its signature, retries, the timeout and the same errors. It returns the decoded JSON.

$created = Attract::site()->request('POST', '/my-route', body: ['title' => 'Hello']);

Show advanced: the engine underneath

The SDK runs on a generated engine, fetchski/attract-cms-api-client. api() reaches it directly, with its own models and getters, for the rare case the methods don’t cover: Attract::site()->api(TestimonialsApi::class)->updateTestimonial(id: $id, testimonial: new Testimonial([...])).

Next: working with results

Ids, counts and the fields you want, in one line.

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Arguments

Named and typed

A body is arguments too

null is not sent

Laravel's own values

Answers

Whole lists, missing documents, jobs

What an API key reaches

Ids

Uploads

Timeouts

Slow routes set their own

The larger one wins

A route without a method

Next: working with results