Ello API

ello.md

Ello API

This is a basic exploration of the Ello API. Completely unofficial, your mileage my vary, don't smash their servers as they are likely very busy.

Methods return HTML for their representation where appropriate which is a nice little pattern. Everything returns application/json.

Like this:

{
   "id": <new post ID>,
   "content": <encoded HTML for display>
}

Authentication

Is session and cookie based. Grab the '_ello_session' cookie in an active Ello browser session.

Streams

Internally the Noise and Friends bit seem to be called "streams" but I can't see how to obtain them.

Obtaining A Single Post

GET https://ello.co/api/v1/posts/post_id.json

Failure 404 Not found, obviously.

Posting Posts

## Simple

POST https://ello.co/api/v1/posts.json

With a multipart/form-data input. One field must be "unsanitized_body", which should look like this:

[
   {
      "kind":"text",
      "data":"test"
   }
]

Links are sent in HTML and Markdown in Markdown.

## Image

Ello automatically uploads images to S3 for display, chucking them to ello-direct-uploads.s3.amazonaws.com - after it knows the image is done, it sends the following.

[
   {
      "kind":"image",
      "data":{
         "url":"some url",
         "via":"direct",
         "alt":"filename.png - though it probably can be a proper alt"
      }
   }
]

Success 200 Failure 422 - Unprocessable Entity

Clearly one can add more than one post to this array.

Editing Posts

PUT https://ello.co/api/v1/posts/[ID of post].json

Success 200 Failure 404 - Not found.

Same format as posting a post above.

Deleting Posts

DELETE https://ello.co/api/v1/posts/[ID of post]

Success 204 Failure 404 - Not found.

Friends List

GET /api/v1/followerships

Adding Comments

POST https://ello.co/api/v1/comments

Same format as posts, but with the addition of parent_post_id as an additional form field.

Removing Comments

PUT https://ello.co/api/v1/comments/

Same format as posts.

Getting Comments

GET https://ello.co/api/v1/comments?parent_post_id=parent_id_of_the_post

https://ello.co/api/v1/availability/username?value=[VALUE]
https://ello.co/api/v1/availability/email?value=[VALUE]
https://ello.co/api/v1/availability/invitation_code?value=[VALUE]

I'm using your notes here to build an app, and I was curious if you happen to know what format to post images in. Do you ASCII-armor the image and then stuff it in the "data" field?

Do you know a way to see, who other users are following / followed by?

To return user data and posts, simply add ".json" to the url like this:
https://ello.co/ello.json

My current issue is figuring how to get the username of the logged-in user, without parsing any html...

Followerships for autocomplete - basically a shorter version of this endpoint...

It would be awesome if you wouldn't post this publicly. The Ello team is tiny, and has enough problems already right now.

@cacheflowe I don't think there is anything wrong with posting this here. The code is already public (we all got it from digging through the site), so if someone has it in them to do something harmful, they probably already know how to retrieve this information just as we have.

That being said, I think if anything the existence of this gist helps you out as a developer of Ello. If you tighten things up on your end to help prevent any future harmful attacks through the use of this information, it has done ya good to come across it. To me, having someone post their findings publicly is better than having them hide it all and devise some evil plan. This way you know some of your code's vulnerabilities, and can proceed how you want with a fix. Github is meant for social coding. Think of this as social beta testing by other developers.

Good luck, it's exciting to watch Ello grow.

@cacheflow It's comments like that which prompt people like me to fork things like this just so they don't disappear forever.

Besides, it's not like there's anything here which is, strictly speaking a vulnerability, it just appears to be isolating the API framework under the hood. Now since the hood itself is kind of crap, it would probably be in Ello's best interests to open up the API to those of us who are more than happy to to take advantage of it.

Ideally, though, that would include implementing OAuth2. Not to mention honouring user privacy settings within the API and if you haven't done that then everything from the manifesto onwards has been pure bullshit. I hope it's not pure bullshit, but I guess we'll just have to wait and see.

Between Tamper Data, HttpRequester and RESTClient it should be fairly simple to extract the methods necessary to get your own code to authenticate and obtain a session ID/cookie instead of always harvesting one from a current browser session. I'd copy and paste, but these things will, of course, pick up the passwords transmitted and it would be silly to post that. Basically, though, just run Tamper Data in the background, log out of Ello and log back in, then export everything Tamper Data picked up and go looking. The bits you want should be on the POST entry for the https://ello.co/enter page (the second appearance of that page).

All three of those tools are for Firefox only, though. Tamper Data is easily the best, but the other two make testing much clearer and somewhat easier to work with. If any of you are feeling particularly brave, though, you could always try forking RESTClient here on GitHub and converting it to Chrome or whatever else you use.

To be totally frank, once I realized I could get most of this information using the Chrome developer tools console, I started doing my own prodding. Believe it or not, it's not to attack Ello. It's to try and slap together a tool for myself so I can share on Ello more easily. That's a good thing, not a bad thing, and if there was an OAuth2 support, then that'd be a real dream. I'd be done already, actually.

It appears ello added cross site script protection to their post method. Have you been able to figure out a way around this yet?

@impulse9489 CSRF protection usually uses a random value present on the pages that are supposed to be requesting or submitting data - the only way around it would be to scrape html, and that's really not very viable, is it?

You can use a csrf token you find in the meta tags. I've been able to figure out that much and scrape the HTML. Unfortunately, the HttpUrlConnection and WebView in Android both seem to end up getting a csrf token that's invalid; the Android stock browser and Chrome for Android seem to be immune. I'm just trying to write a simple photo-sharer for my phone, but I guess this stymies it unless I can find a workaround.

Post a text URI is now: https://ello.co/api/v1/posts

If anyone had luck getting cookie from the enter page using .net HttpClient, could you please help me with that?

using (var client = new HttpClient())
{
_httpResponse = await client.GetAsync("https://ello.co/enter");
_httpResponse.EnsureSuccessStatusCode();
}

after that I get status code 416 'Requested Range Not Satisfiable'

Thanks!