SILK Developer Program

For programmers

SILK uses OAuth 2.0 with the authorization code flow and PKCE (S256), the same flow X, Google and GitHub use, so existing OAuth libraries work. Exchange codes from your server, never from a browser: SILK's endpoints don't allow cross-site browser calls.

Like Facebook's share link and X's post link: send visitors to a network site with the link filled in. If they're signed out, they sign in first. Nothing is posted until they press Post.

<a href="https://pinitin.com/share?url=https%3A%2F%2Fexample.com%2Fstory&title=Great%20story">Share on PinItIn</a>
<a href="https://eatdrama.com/share?url=https%3A%2F%2Fexample.com%2Fstory&text=You%20have%20to%20see%20this">Share on EatDrama</a>
FieldWhat it does
urlThe link to share (required). Tracking bits like utm_ are removed.
titleA title to start with. Without one, the site reads the page's own title.
textWords to start the post with (up to 500 characters). The member can change them.
tagsUp to 5 tags, separated by commas.
viaYour site's short name, kept with the share.
popup=1For a small window: it says "Posted" and closes itself.

To open it in a small window: window.open(link, 'share', 'width=560,height=640').

Addresses

WhatAddress
Allow page (send the member here)https://spidertaz.com/silk/authorize
Passes (POST, from your server)https://spidertaz.com/silk/token
Stop a pass (POST)https://spidertaz.com/silk/revoke
Member profile (GET)https://spidertaz.com/silk/me

The flow

  1. Make a code verifier: 43 to 128 random characters from A-Z a-z 0-9 - . _ ~. Keep it on your server for this sign-in. The challenge is BASE64URL(SHA256(verifier)) without padding.
  2. Send the member to the Allow page:
    https://spidertaz.com/silk/authorize?response_type=code
      &client_id=YOUR_CLIENT_ID
      &redirect_uri=https%3A%2F%2Fexample.com%2Fsilk%2Fcallback
      &scope=profile.read
      &state=RANDOM_VALUE_YOU_CHECK_LATER
      &code_challenge=CHALLENGE
      &code_challenge_method=S256
    redirect_uri must exactly match a return address you added. state is required. Add prompt=consent to always show the page; otherwise a member who already allowed the same permissions goes straight back.
  3. The member comes back to your return address with ?code=...&state=..., or ?error=access_denied&state=... if they cancelled. Check state. The code works once, for 60 seconds.
  4. Swap the code for passes from your server:
    curl -X POST https://spidertaz.com/silk/token \
      -u "YOUR_CLIENT_ID:YOUR_APP_SECRET" \
      -d grant_type=authorization_code \
      -d code=THE_CODE \
      -d redirect_uri=https://example.com/silk/callback \
      -d code_verifier=THE_VERIFIER
    Answer:
    {"access_token":"silk_at_...","token_type":"Bearer","expires_in":3600,
     "refresh_token":"silk_rt_...","scope":"profile.read"}
    Phone and desktop apps (app type "Phone or desktop app") have no secret: send client_id in the body and rely on PKCE.
  5. Use the access pass:
    curl https://spidertaz.com/silk/me -H "Authorization: Bearer silk_at_..."
    {"sub":"3f9c...","name":"SpiderFan","profile_url":"https://spidertaz.com/member/spiderfan"}
    sub is the member's ID for your app only. It stays the same for your app and is different in every other app.

Permissions

PermissionWhat the member seesStatus
profile.readSee your public screen name and profile addressReady
pinitin.postPost on PinItIn as youReady, needs review
eatdrama.postPost on EatDrama as youReady, needs review
arcspoiler.postPost in the ArcSpoiler community as youReady, needs review
wruniverse.postPost War Reports on WRUniverse as youReady, needs review
pintotrav.postPost traveler stories on PinToTrav as youReady, needs review
geodigg.postPost community reports on GeoDigg as youReady, needs review
wrunity.postSuggest links to WRUnity as youReady, needs review
frontiers.postPost War Reports on WRUniverse Frontiers as youReady, needs review
gtageo.postSend GTA 6 tips to GTAGeo as youReady, needs review
newsspoiler.postSend news tips to NewsSpoiler as youReady, needs review

Posting for a member

With a site's posting permission (pinitin.post, eatdrama.post, arcspoiler.post, wruniverse.post, pintotrav.post, geodigg.post, wrunity.post, frontiers.post, gtageo.post or newsspoiler.post) and your app approved in review, post with the member's access pass. Each site checks the pass with SpiderTaz and applies its own posting rules and limits.

curl -X POST https://pinitin.com/api/v1/posts \
  -H "Authorization: Bearer silk_at_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Loved this one","url":"https://example.com/story","title":"Great story","visibility":"public"}'

{"id":123,"url":"https://pinitin.com/post/123"}
SiteAddressFields
PinItInPOST https://pinitin.com/api/v1/poststext, url, title, visibility (public, members, private), allow_repeat
EatDramaPOST https://eatdrama.com/api/v1/poststitle, text, url, post_type (entertainment, celebrity, drama, gossip, lifestyle, post, reaction, clip, status), allow_repeat
ArcSpoilerPOST https://arcspoiler.com/api/v1/poststext, url, category (general, runs, questions, discoveries), allow_repeat. The member needs an ArcSpoiler player profile.
WRUniversePOST https://wruniverse.com/api/v1/poststext, url, visibility (members, private, public), category (general, battle_results, builds, questions, achievements, clan_updates). For verified pilots only; five an hour.
PinToTravPOST https://pintotrav.com/api/v1/postsplace (a PinToTrav destination like kyoto, or a place name like "Savannah, Georgia"), title, text (50 to 6,000 characters, no links), url (shown beside the story), allow_repeat. The member needs a confirmed email; five stories a day.
GeoDiggPOST https://geodigg.com/api/v1/postscity ("City, ST", like "Palm Bay, FL"), title, text, url (added as the source), type (traffic, weather, public-safety, closure, event, community, question, other), timing (now, earlier, scheduled). A member's first 3 reports wait for a moderator; the answer says published or waiting_for_review.
WRUnityPOST https://wrunity.org/api/v1/postsurl (required), title, text, type (resource, lesson_idea, creator, other), allow_repeat. Every suggestion waits for a moderator before it shows.
WRUniverse FrontiersPOST https://frontiers.wruniverse.com/api/v1/postsThe same fields and rules as WRUniverse, with frontiers.post.
GTAGeoPOST https://gtageo.com/api/v1/poststitle and text (required: what was found and how players can check it), url (saved as the source), type (Location, Discovery, Screenshot, Video or Guide, Suggest a Fix, Player Tip, Map Note). Every tip waits for GTAGeo Review before anything changes on the map.
NewsSpoilerPOST https://newsspoiler.com/api/v1/postsurl (required), title, text, place, allow_repeat. Tips are private and reviewed; they are never published by themselves.

Send text, url or both. Every post shows "via" your app's name. If the member shared the same link in the last day you get 409 duplicate with the earlier post; send allow_repeat: true to post it again. Other answers: 401 invalid_token, 403 insufficient_scope, 422 not_posted (the site's own limits or rules, with a plain reason), 429 slow_down.

Renewing and stopping

Access passes last 1 hour. Renewal passes last 60 days and are replaced every time you use one: always keep the newest. Sending an old renewal pass again stops all of that member's passes for your app, in case it was copied.

curl -X POST https://spidertaz.com/silk/token -u "YOUR_CLIENT_ID:YOUR_APP_SECRET" \
  -d grant_type=refresh_token -d refresh_token=silk_rt_...

When a member signs out of your app for good, stop their passes: POST /silk/revoke with token=... and your app's sign-in. If a member removes your app in SILK connected apps, renewing fails with invalid_grant.

Errors

ErrorWhat it means
invalid_clientWrong client ID or app secret, or the app is suspended.
invalid_grantThe code or renewal pass is wrong, used, expired, or the member removed your app.
invalid_requestSomething required is missing, such as state or PKCE.
invalid_scopeYou asked for a permission your app hasn't chosen, or one that isn't ready.
access_deniedThe member tapped Cancel, or your app is in test mode and they aren't a test member.
invalid_token / insufficient_scopeFrom /silk/me: the access pass is wrong or expired, or lacks the permission.
slow_downToo many requests. Wait a minute (limits: 120 a minute from one address, 600 a minute per app).

Rules